diff options
author | Wojtek Kosior <wk@koszkonutek-tmp.pl.eu.org> | 2021-04-30 00:33:56 +0200 |
---|---|---|
committer | Wojtek Kosior <wk@koszkonutek-tmp.pl.eu.org> | 2021-04-30 00:33:56 +0200 |
commit | aa4d426b4d3527d7e166df1a05058c9a4a0f6683 (patch) | |
tree | 4ff17ce8b89a2321b9d0ed4bcfc37c447bcb6820 /openssl-1.1.0h/doc | |
download | smtps-and-pop3s-console-program-aa4d426b4d3527d7e166df1a05058c9a4a0f6683.tar.gz smtps-and-pop3s-console-program-aa4d426b4d3527d7e166df1a05058c9a4a0f6683.zip |
Diffstat (limited to 'openssl-1.1.0h/doc')
457 files changed, 58967 insertions, 0 deletions
diff --git a/openssl-1.1.0h/doc/HOWTO/certificates.txt b/openssl-1.1.0h/doc/HOWTO/certificates.txt new file mode 100644 index 0000000..65f8fc8 --- /dev/null +++ b/openssl-1.1.0h/doc/HOWTO/certificates.txt @@ -0,0 +1,110 @@ +<DRAFT!> + HOWTO certificates + +1. Introduction + +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 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 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. 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 + +Certificates are related to public key cryptography by containing a +public key. To be useful, there must be a corresponding private key +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 -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 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: + + openssl req -new -key privkey.pem -out cert.csr + +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, -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). + +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. + + +4. Creating a self-signed test certificate + +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 + + +5. What to do with the certificate + +If you created everything yourself, or if the certificate authority +was kind enough, your certificate is a raw DER thing in PEM format. +Your key most definitely is if you have followed the examples above. +However, some (most?) certificate authorities will encode them with +things like PKCS7 or PKCS12, or something else. Depending on your +applications, this may be perfectly OK, it all depends on what they +know how to decode. If not, There are a number of OpenSSL tools to +convert between some (most?) formats. + +So, depending on your application, you may have to convert your +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 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 certificate and your private key and can start +using applications that depend on it. + +-- +Richard Levitte diff --git a/openssl-1.1.0h/doc/HOWTO/keys.txt b/openssl-1.1.0h/doc/HOWTO/keys.txt new file mode 100644 index 0000000..1662c17 --- /dev/null +++ b/openssl-1.1.0h/doc/HOWTO/keys.txt @@ -0,0 +1,105 @@ +<DRAFT!> + HOWTO keys + +1. Introduction + +Keys are the basis of public key algorithms and PKI. Keys usually +come in pairs, with one half being the public key and the other half +being the private key. With OpenSSL, the private key contains the +public key information as well, so a public key doesn't need to be +generated separately. + +Public keys come in several flavors, using different cryptographic +algorithms. The most popular ones associated with certificates are +RSA and DSA, and this HOWTO will show how to generate each of them. + + +2. To generate a RSA key + +A RSA key can be used both for encryption and for signing. + +Generating a key for the RSA algorithm is quite easy, all you have to +do is the following: + + openssl genrsa -des3 -out privkey.pem 2048 + +With this variant, you will be prompted for a protecting password. If +you don't want your key to be protected by a password, remove the flag +'-des3' from the command line above. + +The number 2048 is the size of the key, in bits. Today, 2048 or +higher is recommended for RSA keys, as fewer amount of bits is +consider insecure or to be insecure pretty soon. + + +3. To generate a DSA key + +A DSA key can be used for signing only. It is important to +know what a certificate request with a DSA key can really be used for. + +Generating a key for the DSA algorithm is a two-step process. First, +you have to generate parameters from which to generate the key: + + openssl dsaparam -out dsaparam.pem 2048 + +The number 2048 is the size of the key, in bits. Today, 2048 or +higher is recommended for DSA keys, as fewer amount of bits is +consider insecure or to be insecure pretty soon. + +When that is done, you can generate a key using the parameters in +question (actually, several keys can be generated from the same +parameters): + + openssl gendsa -des3 -out privkey.pem dsaparam.pem + +With this variant, you will be prompted for a protecting password. If +you don't want your key to be protected by a password, remove the flag +'-des3' from the command line above. + + +4. To generate an EC key + +An EC key can be used both for key agreement (ECDH) and signing (ECDSA). + +Generating a key for ECC is similar to generating a DSA key. These are +two-step processes. First, you have to get the EC parameters from which +the key will be generated: + + openssl ecparam -name prime256v1 -out prime256v1.pem + +The prime256v1, or NIST P-256, which stands for 'X9.62/SECG curve over +a 256-bit prime field', is the name of an elliptic curve which generates the +parameters. You can use the following command to list all supported curves: + + openssl ecparam -list_curves + +When that is done, you can generate a key using the created parameters (several +keys can be produced from the same parameters): + + openssl genpkey -des3 -paramfile prime256v1.pem -out private.key + +With this variant, you will be prompted for a password to protect your key. +If you don't want your key to be protected by a password, remove the flag +'-des3' from the command line above. + +You can also directly generate the key in one step: + + openssl ecparam -genkey -name prime256v1 -out private.key + +or + + openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 + + +5. NOTE + +If you intend to use the key together with a server certificate, +it may be reasonable to avoid protecting it with a password, since +otherwise someone would have to type in the password every time the +server needs to access the key. + +For X25519, it's treated as a distinct algorithm but not as one of +the curves listed with 'ecparam -list_curves' option. You can use +the following command to generate an X25519 key: + + openssl genpkey -algorithm X25519 -out xkey.pem diff --git a/openssl-1.1.0h/doc/HOWTO/proxy_certificates.txt b/openssl-1.1.0h/doc/HOWTO/proxy_certificates.txt new file mode 100644 index 0000000..642bec9 --- /dev/null +++ b/openssl-1.1.0h/doc/HOWTO/proxy_certificates.txt @@ -0,0 +1,319 @@ + HOWTO proxy certificates + +0. WARNING + +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 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 + +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. + +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. + +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. + +For these reasons, OpenSSL requires that the use of proxy certificates be +explicitly allowed. Currently, this can be done using the following methods: + + - if the application directly calls X509_verify_cert(), it can first call: + + 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(). + + - proxy certificate validation can be enabled before starting the application + by setting the environment variable OPENSSL_ALLOW_PROXY_CERTS. + +In the future, it might be possible to enable proxy certificates by editing +openssl.cnf. + + +3. How to create proxy certificates + +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. + basicConstraints=CA:FALSE + + # Usual authority key ID + authorityKeyIdentifier=keyid,issuer:always + + # The extension which marks this certificate as a proxy + proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB + +It's also possible to specify the proxy extension in a separate section: + + proxyCertInfo=critical,@proxy_ext + + [ proxy_ext ] + language=id-ppl-anyLanguage + pathlen=0 + policy=text:BC + +The policy value has a specific syntax, {syntag}:{string}, where the syntag +determines what will be done with the string. The following syntags are +recognised: + + text indicates that the string is simply bytes, without any encoding: + + 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): + + 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 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 lines, e.g. XML documents). + +The 'policy' setting can be split up in multiple lines like this: + + 0.policy=This is + 1.policy= a multi- + 2.policy=line policy. + +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 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 + +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 + + +4. How to have your application interpret the policy? + +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 figuring out how to pass data between your +application and the certificate validation procedure. + +You need the following ingredients: + + - 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 data structure that is shared between your application code and the + callback. + + - a wrapper function that sets it all up. + + - an ex_data index function that creates an index into the generic ex_data + store that is attached to an X509 validation context. + +Here is some skeleton code you can fill in: + + #include <string.h> + #include <netdb.h> + #include <openssl/x509.h> + #include <openssl/x509v3.h> + + #define total_rights 25 + + /* + * In this example, I will use a view of granted rights as a bit + * array, one bit for each possible right. + */ + typedef struct your_rights { + unsigned char rights[(total_rights + 7) / 8]; + } YOUR_RIGHTS; + + /* + * The following procedure will create an index for the ex_data + * store in the X509 validation context the first time it's called. + * Subsequent calls will return the same index. */ + static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx) + { + static volatile int idx = -1; + if (idx < 0) { + X509_STORE_lock(X509_STORE_CTX_get0_store(ctx)); + if (idx < 0) { + idx = X509_STORE_CTX_get_ex_new_index(0, + "for verify callback", + NULL,NULL,NULL); + } + X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx)); + } + return idx; + } + + /* Callback to be given to the X509 validation procedure. */ + static int verify_callback(int ok, X509_STORE_CTX *ctx) + { + if (ok == 1) { + /* + * It's REALLY important you keep the proxy policy + * check within this section. It's important to know + * that when ok is 1, the certificates are checked + * from top to bottom. You get the CA root first, + * followed by the possible chain of intermediate + * CAs, followed by the EE certificate, followed by + * the possible proxy certificates. + */ + X509 *xs = X509_STORE_CTX_get_current_cert(ctx); + + if (X509_get_extension_flags(xs) & EXFLAG_PROXY) { + YOUR_RIGHTS *rights = + (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, + get_proxy_auth_ex_data_idx(ctx)); + PROXY_CERT_INFO_EXTENSION *pci = + X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL); + + switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) { + case NID_Independent: + /* + * Do whatever you need to grant explicit rights to + * this particular proxy certificate, usually by + * pulling them from some database. If there are none + * to be found, clear all rights (making this and any + * subsequent proxy certificate void of any rights). + */ + memset(rights->rights, 0, sizeof(rights->rights)); + break; + case NID_id_ppl_inheritAll: + /* + * This is basically a NOP, we simply let the current + * rights stand as they are. + */ + break; + default: + /* This is usually the most complex section of code. + * You really do whatever you want as long as you + * follow RFC 3820. In the example we use here, the + * simplest thing to do is to build another, temporary + * bit array and fill it with the rights granted by + * the current proxy certificate, then use it as a + * mask on the accumulated rights bit array, and + * 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)); + + /* + * process_rights() is supposed to be a procedure + * that takes a string and it's length, interprets + * it and sets the bits in the YOUR_RIGHTS pointed + * at by the third argument. + */ + process_rights((char *) pci->proxyPolicy->policy->data, + pci->proxyPolicy->policy->length, + &tmp_rights); + + for(i = 0; i < total_rights / 8; i++) + rights->rights[i] &= tmp_rights.rights[i]; + } + break; + } + PROXY_CERT_INFO_EXTENSION_free(pci); + } else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) { + /* We have an EE certificate, let's use it to set default! */ + YOUR_RIGHTS *rights = + (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, + get_proxy_auth_ex_data_idx(ctx)); + + /* The following procedure finds out what rights the owner + * of the current certificate has, and sets them in the + * YOUR_RIGHTS structure pointed at by the second + * argument. + */ + set_default_rights(xs, rights); + } + } + return ok; + } + + static int my_X509_verify_cert(X509_STORE_CTX *ctx, + YOUR_RIGHTS *needed_rights) + { + int ok; + int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) = + X509_STORE_CTX_get_verify_cb(ctx); + YOUR_RIGHTS rights; + + X509_STORE_CTX_set_verify_cb(ctx, verify_callback); + X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx), &rights); + X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS); + ok = X509_verify_cert(ctx); + + if (ok == 1) { + ok = check_needed_rights(rights, needed_rights); + } + + X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb); + + return ok; + } + + +If you use SSL or TLS, you can easily set up a callback to have the +certificates checked properly, using the code above: + + SSL_CTX_set_cert_verify_callback(s_ctx, my_X509_verify_cert, &needed_rights); + + +-- +Richard Levitte diff --git a/openssl-1.1.0h/doc/README b/openssl-1.1.0h/doc/README new file mode 100644 index 0000000..cac4115 --- /dev/null +++ b/openssl-1.1.0h/doc/README @@ -0,0 +1,20 @@ + +README This file + +fingerprints.txt + PGP fingerprints of authorised release signers + +standards.txt + Moved to the web, https://www.openssl.org/docs/standards.html + +HOWTO/ + A few how-to documents; not necessarily up-to-date +apps/ + The openssl command-line tools; start with openssl.pod +ssl/ + The SSL library; start with ssl.pod +crypto/ + The cryptographic library; start with crypto.pod + +Formatted versions of the manpages (apps,ssl,crypto) can be found at + https://www.openssl.org/docs/manpages.html diff --git a/openssl-1.1.0h/doc/apps/CA.pl.pod b/openssl-1.1.0h/doc/apps/CA.pl.pod new file mode 100644 index 0000000..a7f3970 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/CA.pl.pod @@ -0,0 +1,214 @@ +=pod + +=head1 NAME + +CA.pl - friendlier interface for OpenSSL certificate programs + +=head1 SYNOPSIS + +B<CA.pl> +B<-?> | +B<-h> | +B<-help> + +B<CA.pl> +B<-newcert> | +B<-newreq> | +B<-newreq-nodes> | +B<-xsign> | +B<-sign> | +B<-signCA> | +B<-signcert> | +B<-crl> | +B<-newca> +[B<-extra-cmd> extra-params] + +B<CA.pl> B<-pkcs12> [B<-extra-pkcs12> extra-params] [B<certname>] + +B<CA.pl> B<-verify> [B<-extra-verify> extra-params] B<certfile>... + +B<CA.pl> B<-revoke> [B<-extra-ca> extra-params] B<certfile> [B<reason>] + +=head1 DESCRIPTION + +The B<CA.pl> script is a perl script that supplies the relevant command line +arguments to the B<openssl> command for some common certificate operations. +It is intended to simplify the process of certificate creation and management +by the use of some simple options. + +=head1 OPTIONS + +=over 4 + +=item B<?>, B<-h>, B<-help> + +prints a usage message. + +=item B<-newcert> + +creates a new self signed certificate. The private key is written to the file +"newkey.pem" and the request written to the file "newreq.pem". +This argument invokes B<openssl req> command. + +=item B<-newreq> + +creates a new certificate request. The private key is written to the file +"newkey.pem" and the request written to the file "newreq.pem". +Executes B<openssl req> command below the hood. + +=item B<-newreq-nodes> + +is like B<-newreq> except that the private key will not be encrypted. +Uses B<openssl req> command. + +=item B<-newca> + +creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert> +and B<-xsign> options). The user is prompted to enter the filename of the CA +certificates (which should also contain the private key) or by hitting ENTER +details of the CA will be prompted for. The relevant files and directories +are created in a directory called "demoCA" in the current directory. +B<openssl req> and B<openssl ca> commands are get invoked. + +=item B<-pkcs12> + +create a PKCS#12 file containing the user certificate, private key and CA +certificate. It expects the user certificate and private key to be in the +file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem, +it creates a file "newcert.p12". This command can thus be called after the +B<-sign> option. The PKCS#12 file can be imported directly into a browser. +If there is an additional argument on the command line it will be used as the +"friendly name" for the certificate (which is typically displayed in the browser +list box), otherwise the name "My Certificate" is used. +Delegates work to B<openssl pkcs12> command. + +=item B<-sign>, B<-signcert>, B<-xsign> + +calls the B<ca> program to sign a certificate request. It expects the request +to be in the file "newreq.pem". The new certificate is written to the file +"newcert.pem" except in the case of the B<-xsign> option when it is written +to standard output. Leverages B<openssl ca> command. + +=item B<-signCA> + +this option is the same as the B<-signreq> option except it uses the configuration +file section B<v3_ca> and so makes the signed request a valid CA certificate. This +is useful when creating intermediate CA from a root CA. +Extra params are passed on to B<openssl ca> command. + +=item B<-signcert> + +this option is the same as B<-sign> except it expects a self signed certificate +to be present in the file "newreq.pem". +Extra params are passed on to B<openssl x509> and B<openssl ca> commands. + +=item B<-crl> + +generate a CRL. Executes B<openssl ca> command. + +=item B<-revoke certfile [reason]> + +revoke the certificate contained in the specified B<certfile>. An optional +reason may be specified, and must be one of: B<unspecified>, +B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>, +B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>. +Leverages B<openssl ca> command. + +=item B<-verify> + +verifies certificates against the CA certificate for "demoCA". If no certificates +are specified on the command line it tries to verify the file "newcert.pem". +Invokes B<openssl verify> command. + +=item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> <extra-params> + +The purpose of these parameters is to allow optional parameters to be supplied +to B<openssl> that this command executes. The B<-extra-cmd> are specific to the +option being used and the B<openssl> command getting invoked. For example +when this command invokes B<openssl req> extra parameters can be passed on +with the B<-extra-req> parameter. The +B<openssl> commands being invoked per option are documented below. +Users should consult B<openssl> command documentation for more information. + +=back + +=head1 EXAMPLES + +Create a CA hierarchy: + + CA.pl -newca + +Complete certificate creation example: create a CA, create a request, sign +the request and finally create a PKCS#12 file containing it. + + CA.pl -newca + CA.pl -newreq + CA.pl -signreq + CA.pl -pkcs12 "My Test Certificate" + +=head1 DSA CERTIFICATES + +Although the B<CA.pl> creates RSA CAs and requests it is still possible to +use it with DSA certificates and requests using the L<req(1)> command +directly. The following example shows the steps that would typically be taken. + +Create some DSA parameters: + + openssl dsaparam -out dsap.pem 1024 + +Create a DSA CA certificate and private key: + + openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem + +Create the CA directories and files: + + CA.pl -newca + +enter cacert.pem when prompted for the CA file name. + +Create a DSA certificate request and private key (a different set of parameters +can optionally be created first): + + openssl req -out newreq.pem -newkey dsa:dsap.pem + +Sign the request: + + CA.pl -signreq + +=head1 NOTES + +Most of the filenames mentioned can be modified by editing the B<CA.pl> script. + +If the demoCA directory already exists then the B<-newca> command will not +overwrite it and will do nothing. This can happen if a previous call using +the B<-newca> option terminated abnormally. To get the correct behaviour +delete the demoCA directory if it already exists. + +Under some environments it may not be possible to run the B<CA.pl> script +directly (for example Win32) and the default configuration file location may +be wrong. In this case the command: + + perl -S CA.pl + +can be used and the B<OPENSSL_CONF> environment variable changed to point to +the correct path of the configuration file. + +The script is intended as a simple front end for the B<openssl> program for use +by a beginner. Its behaviour isn't always what is wanted. For more control over the +behaviour of the certificate commands call the B<openssl> command directly. + +=head1 SEE ALSO + +L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>, +L<config(5)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/asn1parse.pod b/openssl-1.1.0h/doc/apps/asn1parse.pod new file mode 100644 index 0000000..3c607e8 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/asn1parse.pod @@ -0,0 +1,209 @@ +=pod + +=head1 NAME + +openssl-asn1parse, +asn1parse - ASN.1 parsing tool + +=head1 SYNOPSIS + +B<openssl> B<asn1parse> +[B<-help>] +[B<-inform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-offset number>] +[B<-length number>] +[B<-i>] +[B<-oid filename>] +[B<-dump>] +[B<-dlimit num>] +[B<-strparse offset>] +[B<-genstr string>] +[B<-genconf file>] +[B<-strictpem>] + +=head1 DESCRIPTION + +The B<asn1parse> command is a diagnostic utility that can parse ASN.1 +structures. It can also be used to extract data from ASN.1 formatted data. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform> B<DER|PEM> + +the input format. B<DER> is binary format and B<PEM> (the default) is base64 +encoded. + +=item B<-in filename> + +the input file, default is standard input + +=item B<-out filename> + +output file to place the DER encoded data into. If this +option is not present then no data will be output. This is most useful when +combined with the B<-strparse> option. + +=item B<-noout> + +don't output the parsed version of the input file. + +=item B<-offset number> + +starting offset to begin parsing, default is start of file. + +=item B<-length number> + +number of bytes to parse, default is until end of file. + +=item B<-i> + +indents the output according to the "depth" of the structures. + +=item B<-oid filename> + +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 +option can be used multiple times to "drill down" into a nested structure. + +=item B<-genstr string>, B<-genconf file> + +generate encoded data based on B<string>, B<file> or both using +L<ASN1_generate_nconf(3)> format. If B<file> only is +present then the string is obtained from the default section using the name +B<asn1>. The encoded data is passed through the ASN1 parser and printed out as +though it came from a file, the contents can thus be examined and written to a +file using the B<out> option. + +=item B<-strictpem> + +If this option is used then B<-inform> will be ignored. Without this option any +data in a PEM format input file will be treated as being base64 encoded and +processed whether it has the normal PEM BEGIN and END markers or not. This +option will ignore any data prior to the start of the BEGIN marker, or after an +END marker in a PEM file. + +=back + +=head2 Output + +The output will typically contain lines like this: + + 0:d=0 hl=4 l= 681 cons: SEQUENCE + +..... + + 229:d=3 hl=3 l= 141 prim: BIT STRING + 373:d=2 hl=3 l= 162 cons: cont [ 3 ] + 376:d=3 hl=3 l= 159 cons: SEQUENCE + 379:d=4 hl=2 l= 29 cons: SEQUENCE + 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier + 386:d=5 hl=2 l= 22 prim: OCTET STRING + 410:d=4 hl=2 l= 112 cons: SEQUENCE + 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier + 417:d=5 hl=2 l= 105 prim: OCTET STRING + 524:d=4 hl=2 l= 12 cons: SEQUENCE + +..... + +This example is part of a self-signed certificate. Each line starts with the +offset in decimal. B<d=XX> specifies the current depth. The depth is increased +within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length +(tag and length octets) of the current type. B<l=XX> gives the length of +the contents octets. + +The B<-i> option can be used to make the output more readable. + +Some knowledge of the ASN.1 structure is needed to interpret the output. + +In this example the BIT STRING at offset 229 is the certificate public key. +The contents octets of this will contain the public key information. This can +be examined using the option B<-strparse 229> to yield: + + 0:d=0 hl=3 l= 137 cons: SEQUENCE + 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897 + 135:d=1 hl=2 l= 3 prim: INTEGER :010001 + +=head1 NOTES + +If an OID is not part of OpenSSL's internal table it will be represented in +numerical form (for example 1.2.3.4). The file passed to the B<-oid> option +allows additional OIDs to be included. Each line consists of three columns, +the first column is the OID in numerical format and should be followed by white +space. The second column is the "short name" which is a single word followed +by white space. The final column is the rest of the line and is the +"long name". B<asn1parse> displays the long name. Example: + +C<1.2.3.4 shortName A long name> + +=head1 EXAMPLES + +Parse a file: + + openssl asn1parse -in file.pem + +Parse a DER file: + + openssl asn1parse -inform DER -in file.der + +Generate a simple UTF8String: + + openssl asn1parse -genstr 'UTF8:Hello World' + +Generate and write out a UTF8String, don't print parsed output: + + openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der + +Generate using a config file: + + openssl asn1parse -genconf asn1.cnf -noout -out asn1.der + +Example config file: + + asn1=SEQUENCE:seq_sect + + [seq_sect] + + field1=BOOL:TRUE + field2=EXP:0, UTF8:some random string + + +=head1 BUGS + +There should be options to change the format of output lines. The output of some +ASN.1 types is not well handled (if at all). + +=head1 SEE ALSO + +L<ASN1_generate_nconf(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/ca.pod b/openssl-1.1.0h/doc/apps/ca.pod new file mode 100644 index 0000000..9918a13 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/ca.pod @@ -0,0 +1,724 @@ +=pod + +=head1 NAME + +openssl-ca, +ca - sample minimal CA application + +=head1 SYNOPSIS + +B<openssl> B<ca> +[B<-help>] +[B<-verbose>] +[B<-config filename>] +[B<-name section>] +[B<-gencrl>] +[B<-revoke file>] +[B<-valid file>] +[B<-status serial>] +[B<-updatedb>] +[B<-crl_reason reason>] +[B<-crl_hold instruction>] +[B<-crl_compromise time>] +[B<-crl_CA_compromise time>] +[B<-crldays days>] +[B<-crlhours hours>] +[B<-crlexts section>] +[B<-startdate date>] +[B<-enddate date>] +[B<-days arg>] +[B<-md arg>] +[B<-policy arg>] +[B<-keyfile arg>] +[B<-keyform PEM|DER>] +[B<-key arg>] +[B<-passin arg>] +[B<-cert file>] +[B<-selfsign>] +[B<-in file>] +[B<-out file>] +[B<-notext>] +[B<-outdir dir>] +[B<-infiles>] +[B<-spkac file>] +[B<-ss_cert file>] +[B<-preserveDN>] +[B<-noemailDN>] +[B<-batch>] +[B<-msie_hack>] +[B<-extensions section>] +[B<-extfile section>] +[B<-engine id>] +[B<-subj arg>] +[B<-utf8>] +[B<-create_serial>] +[B<-multivalue-rdn>] + +=head1 DESCRIPTION + +The B<ca> command is a minimal CA application. It can be used +to sign certificate requests in a variety of forms and generate +CRLs it also maintains a text database of issued certificates +and their status. + +The options descriptions will be divided into each purpose. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-verbose> + +this prints extra details about the operations being performed. + +=item B<-config filename> + +specifies the configuration file to use. +Optional; for a description of the default value, +see L<openssl(1)/COMMAND SUMMARY>. + +=item B<-name section> + +specifies the configuration file section to use (overrides +B<default_ca> in the B<ca> section). + +=item B<-in filename> + +an input filename containing a single certificate request to be +signed by the CA. + +=item B<-ss_cert filename> + +a single self-signed certificate to be signed by the CA. + +=item B<-spkac filename> + +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 input and output format. + +=item B<-infiles> + +if present this should be the last option, all subsequent arguments +are taken as the names of files containing certificate requests. + +=item B<-out filename> + +the output file to output certificates to. The default is standard +output. The certificate details will also be printed out to this +file in PEM format (except that B<-spkac> outputs DER format). + +=item B<-outdir directory> + +the directory to output certificates to. The certificate will be +written to a filename consisting of the serial number in hex with +".pem" appended. + +=item B<-cert> + +the CA certificate file. + +=item B<-keyfile filename> + +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 +systems the command line arguments are visible (e.g. Unix with +the 'ps' utility) this option should be used with caution. + +=item B<-selfsign> + +indicates the issued certificates are to be signed with the key +the certificate requests were signed with (given with B<-keyfile>). +Certificate requests signed with a different key are ignored. If +B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is +ignored. + +A consequence of using B<-selfsign> is that the self-signed +certificate appears among the entries in the certificate database +(see the configuration option B<database>), and uses the same +serial number counter as all other certificates sign with the +self-signed certificate. + +=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)>. + +=item B<-notext> + +don't output the text form of a certificate to the output file. + +=item B<-startdate date> + +this allows the start date to be explicitly set. The format of the +date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). + +=item B<-enddate date> + +this allows the expiry date to be explicitly set. The format of the +date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). + +=item B<-days arg> + +the number of days to certify the certificate for. + +=item B<-md alg> + +the message digest to use. +Any digest supported by the OpenSSL B<dgst> command can be used. +This option also applies to CRLs. + +=item B<-policy arg> + +this option defines the CA "policy" to use. This is a section in +the configuration file which decides which fields should be mandatory +or match the CA certificate. Check out the B<POLICY FORMAT> section +for more information. + +=item B<-msie_hack> + +this is a legacy option to make B<ca> work with very old versions of +the IE certificate enrollment control "certenr3". It used UniversalStrings +for almost everything. Since the old control has various security bugs +its use is strongly discouraged. The newer control "Xenroll" does not +need this option. + +=item B<-preserveDN> + +Normally the DN order of a certificate is the same as the order of the +fields in the relevant policy section. When this option is set the order +is the same as the request. This is largely for compatibility with the +older IE enrollment control which would only accept certificates if their +DNs match the order of the request. This is not needed for Xenroll. + +=item B<-noemailDN> + +The DN of a certificate can contain the EMAIL field if present in the +request DN, however it is good policy just having the e-mail set into +the altName extension of the certificate. When this option is set the +EMAIL field is removed from the certificate' subject and set only in +the, eventually present, extensions. The B<email_in_dn> keyword can be +used in the configuration file to enable this behaviour. + +=item B<-batch> + +this sets the batch mode. In this mode no questions will be asked +and all certificates will be certified automatically. + +=item B<-extensions section> + +the section of the configuration file containing certificate extensions +to be added when a certificate is issued (defaults to B<x509_extensions> +unless the B<-extfile> option is used). If no extension section is +present then, a V1 certificate is created. If the extension section +is present (even if it is empty), then a V3 certificate is created. See the:w +L<x509v3_config(5)> manual page for details of the +extension section format. + +=item B<-extfile file> + +an additional configuration file to read certificate extensions from +(using the default section unless the B<-extensions> option is also +used). + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<ca> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-subj arg> + +supersedes subject name given in the request. +The arg must be formatted as I</type0=value0/type1=value1/type2=...>, +characters may be escaped by \ (backslash), no spaces are skipped. + +=item B<-utf8> + +this option causes field values to be interpreted as UTF8 strings, by +default they are interpreted as ASCII. This means that the field +values, whether prompted from a terminal or obtained from a +configuration file, must be valid UTF8 strings. + +=item B<-create_serial> + +if reading serial from the text file as specified in the configuration +fails, specifying this option creates a new random serial to be used as next +serial number. + +=item B<-multivalue-rdn> + +This option causes the -subj argument to be interpreted with full +support for multivalued RDNs. Example: + +I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> + +If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>. + +=back + +=head1 CRL OPTIONS + +=over 4 + +=item B<-gencrl> + +this option generates a CRL based on information in the index file. + +=item B<-crldays num> + +the number of days before the next CRL is due. That is the days from +now to place in the CRL nextUpdate field. + +=item B<-crlhours num> + +the number of hours before the next CRL is due. + +=item B<-revoke filename> + +a filename containing a certificate to revoke. + +=item B<-valid filename> + +a filename containing a certificate to add a Valid certificate entry. + +=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>, +B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>, +B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case +insensitive. Setting any revocation reason will make the CRL v2. + +In practice B<removeFromCRL> is not particularly useful because it is only used +in delta CRLs which are not currently implemented. + +=item B<-crl_hold instruction> + +This sets the CRL revocation reason code to B<certificateHold> and the hold +instruction to B<instruction> which must be an OID. Although any OID can be +used only B<holdInstructionNone> (the use of which is discouraged by RFC2459) +B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used. + +=item B<-crl_compromise time> + +This sets the revocation reason to B<keyCompromise> and the compromise time to +B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>. + +=item B<-crl_CA_compromise time> + +This is the same as B<crl_compromise> except the revocation reason is set to +B<CACompromise>. + +=item B<-crlexts section> + +the section of the configuration file containing CRL extensions to +include. If no CRL extension section is present then a V1 CRL is +created, if the CRL extension section is present (even if it is +empty) then a V2 CRL is created. The CRL extensions specified are +CRL extensions and B<not> CRL entry extensions. It should be noted +that some software (for example Netscape) can't handle V2 CRLs. See +L<x509v3_config(5)> manual page for details of the +extension section format. + +=back + +=head1 CONFIGURATION FILE OPTIONS + +The section of the configuration file containing options for B<ca> +is found as follows: If the B<-name> command line option is used, +then it names the section to be used. Otherwise the section to +be used must be named in the B<default_ca> option of the B<ca> section +of the configuration file (or in the default section of the +configuration file). Besides B<default_ca>, the following options are +read directly from the B<ca> section: + RANDFILE + preserve + msie_hack +With the exception of B<RANDFILE>, this is probably a bug and may +change in future releases. + +Many of the configuration file options are identical to command line +options. Where the option is present in the configuration file +and the command line the command line value is used. Where an +option is described as mandatory then it must be present in +the configuration file or the command line equivalent (if +any) used. + +=over 4 + +=item B<oid_file> + +This specifies a file containing additional B<OBJECT IDENTIFIERS>. +Each line of the file should consist of the numerical form of the +object identifier followed by white space then the short name followed +by white space and finally the long name. + +=item B<oid_section> + +This specifies a section in the configuration file containing extra +object identifiers. Each line should consist of the short name of the +object identifier followed by B<=> and the numerical form. The short +and long names are the same when this option is used. + +=item B<new_certs_dir> + +the same as the B<-outdir> command line option. It specifies +the directory where new certificates will be placed. Mandatory. + +=item B<certificate> + +the same as B<-cert>. It gives the file containing the CA +certificate. Mandatory. + +=item B<private_key> + +same as the B<-keyfile> option. The file containing the +CA private key. Mandatory. + +=item B<RANDFILE> + +a file used to read and write random number seed information, or +an EGD socket (see L<RAND_egd(3)>). + +=item B<default_days> + +the same as the B<-days> option. The number of days to certify +a certificate for. + +=item B<default_startdate> + +the same as the B<-startdate> option. The start date to certify +a certificate for. If not set the current time is used. + +=item B<default_enddate> + +the same as the B<-enddate> option. Either this option or +B<default_days> (or the command line equivalents) must be +present. + +=item B<default_crl_hours default_crl_days> + +the same as the B<-crlhours> and the B<-crldays> options. These +will only be used if neither command line option is present. At +least one of these must be present to generate a CRL. + +=item B<default_md> + +the same as the B<-md> option. Mandatory. + +=item B<database> + +the text database file to use. Mandatory. This file must be present +though initially it will be empty. + +=item B<unique_subject> + +if the value B<yes> is given, the valid certificate entries in the +database must have unique subjects. if the value B<no> is given, +several valid certificate entries may have the exact same subject. +The default value is B<yes>, to be compatible with older (pre 0.9.8) +versions of OpenSSL. However, to make CA certificate roll-over easier, +it's recommended to use the value B<no>, especially if combined with +the B<-selfsign> command line option. + +Note that it is valid in some circumstances for certificates to be created +without any subject. In the case where there are multiple certificates without +subjects this does not count as a duplicate. + +=item B<serial> + +a text file containing the next serial number to use in hex. Mandatory. +This file must be present and contain a valid serial number. + +=item B<crlnumber> + +a text file containing the next CRL number to use in hex. The crl number +will be inserted in the CRLs only if this file exists. If this file is +present, it must contain a valid CRL number. + +=item B<x509_extensions> + +the same as B<-extensions>. + +=item B<crl_extensions> + +the same as B<-crlexts>. + +=item B<preserve> + +the same as B<-preserveDN> + +=item B<email_in_dn> + +the same as B<-noemailDN>. If you want the EMAIL field to be removed +from the DN of the certificate simply set this to 'no'. If not present +the default is to allow for the EMAIL filed in the certificate's DN. + +=item B<msie_hack> + +the same as B<-msie_hack> + +=item B<policy> + +the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section +for more information. + +=item B<name_opt>, B<cert_opt> + +these options allow the format used to display the certificate details +when asking the user to confirm signing. All the options supported by +the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used +here, except the B<no_signame> and B<no_sigdump> are permanently set +and cannot be disabled (this is because the certificate signature cannot +be displayed because the certificate has not been signed at this point). + +For convenience the values B<ca_default> are accepted by both to produce +a reasonable output. + +If neither option is present the format used in earlier versions of +OpenSSL is used. Use of the old format is B<strongly> discouraged because +it only displays fields mentioned in the B<policy> section, mishandles +multicharacter string types and does not display extensions. + +=item B<copy_extensions> + +determines how extensions in certificate requests should be handled. +If set to B<none> or this option is not present then extensions are +ignored and not copied to the certificate. If set to B<copy> then any +extensions present in the request that are not already present are copied +to the certificate. If set to B<copyall> then all extensions in the +request are copied to the certificate: if the extension is already present +in the certificate it is deleted first. See the B<WARNINGS> section before +using this option. + +The main use of this option is to allow a certificate request to supply +values for certain extensions such as subjectAltName. + +=back + +=head1 POLICY FORMAT + +The policy section consists of a set of variables corresponding to +certificate DN fields. If the value is "match" then the field value +must match the same field in the CA certificate. If the value is +"supplied" then it must be present. If the value is "optional" then +it may be present. Any fields not mentioned in the policy section +are silently deleted, unless the B<-preserveDN> option is set but +this can be regarded more of a quirk than intended behaviour. + +=head1 SPKAC FORMAT + +The input to the B<-spkac> command line option is a Netscape +signed public key and challenge. This will usually come from +the B<KEYGEN> tag in an HTML form to create a new private key. +It is however possible to create SPKACs using the B<spkac> utility. + +The file should contain the variable SPKAC set to the value of +the SPKAC and also the required DN components as name value pairs. +If you need to include the same component twice then it can be +preceded by a number and a '.'. + +When processing SPKAC format, the output is DER if the 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 +already set up and the relevant files already exist. This usually +involves creating a CA certificate and private key with B<req>, a +serial number file and an empty index file and placing them in +the relevant directories. + +To use the sample configuration file below the directories demoCA, +demoCA/private and demoCA/newcerts would be created. The CA +certificate would be copied to demoCA/cacert.pem and its private +key to demoCA/private/cakey.pem. A file demoCA/serial would be +created containing for example "01" and the empty index file +demoCA/index.txt. + + +Sign a certificate request: + + openssl ca -in req.pem -out newcert.pem + +Sign a certificate request, using CA extensions: + + openssl ca -in req.pem -extensions v3_ca -out newcert.pem + +Generate a CRL + + openssl ca -gencrl -out crl.pem + +Sign several requests: + + openssl ca -infiles req1.pem req2.pem req3.pem + +Certify a Netscape SPKAC: + + openssl ca -spkac spkac.txt + +A sample SPKAC file (the SPKAC line has been truncated for clarity): + + SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 + CN=Steve Test + emailAddress=steve@openssl.org + 0.OU=OpenSSL Group + 1.OU=Another Group + +A sample configuration file with the relevant sections for B<ca>: + + [ ca ] + default_ca = CA_default # The default ca section + + [ CA_default ] + + dir = ./demoCA # top dir + database = $dir/index.txt # index file. + new_certs_dir = $dir/newcerts # new certs dir + + certificate = $dir/cacert.pem # The CA cert + serial = $dir/serial # serial no file + private_key = $dir/private/cakey.pem# CA private key + RANDFILE = $dir/private/.rand # random number file + + default_days = 365 # how long to certify for + default_crl_days= 30 # how long before next CRL + default_md = md5 # md to use + + policy = policy_any # default policy + email_in_dn = no # Don't add the email into cert DN + + name_opt = ca_default # Subject name display option + cert_opt = ca_default # Certificate display option + copy_extensions = none # Don't copy extensions from request + + [ policy_any ] + countryName = supplied + stateOrProvinceName = optional + organizationName = optional + organizationalUnitName = optional + commonName = supplied + emailAddress = optional + +=head1 FILES + +Note: the location of all files can change either by compile time options, +configuration file entries, environment variables or command line options. +The values below reflect the default values. + + /usr/local/ssl/lib/openssl.cnf - master configuration file + ./demoCA - main CA directory + ./demoCA/cacert.pem - CA certificate + ./demoCA/private/cakey.pem - CA private key + ./demoCA/serial - CA serial number file + ./demoCA/serial.old - CA serial number backup file + ./demoCA/index.txt - CA text database file + ./demoCA/index.txt.old - CA text database backup file + ./demoCA/certs - certificate output file + ./demoCA/.rnd - CA random seed information + +=head1 RESTRICTIONS + +The text database index file is a critical part of the process and +if corrupted it can be difficult to fix. It is theoretically possible +to rebuild the index file from all the issued certificates and a current +CRL: however there is no option to do this. + +V2 CRL features like delta CRLs are not currently supported. + +Although several requests can be input and handled at once it is only +possible to include one SPKAC or self-signed certificate. + +=head1 BUGS + +The use of an in-memory text database can cause problems when large +numbers of certificates are present because, as the name implies +the database has to be kept in memory. + +The B<ca> command really needs rewriting or the required functionality +exposed at either a command or interface level so a more friendly utility +(perl script or GUI) can handle things properly. The script +B<CA.pl> helps a little but not very much. + +Any fields in a request that are not present in a policy are silently +deleted. This does not happen if the B<-preserveDN> option is used. To +enforce the absence of the EMAIL field within the DN, as suggested by +RFCs, regardless the contents of the request' subject the B<-noemailDN> +option can be used. The behaviour should be more friendly and +configurable. + +Canceling some commands by refusing to certify a certificate can +create an empty file. + +=head1 WARNINGS + +The B<ca> command is quirky and at times downright unfriendly. + +The B<ca> utility was originally meant as an example of how to do things +in a CA. It was not supposed to be used as a full blown CA itself: +nevertheless some people are using it for this purpose. + +The B<ca> command is effectively a single user command: no locking is +done on the various files and attempts to run more than one B<ca> command +on the same database can have unpredictable results. + +The B<copy_extensions> option should be used with caution. If care is +not taken then it can be a security risk. For example if a certificate +request contains a basicConstraints extension with CA:TRUE and the +B<copy_extensions> value is set to B<copyall> and the user does not spot +this when the certificate is displayed then this will hand the requester +a valid CA certificate. + +This situation can be avoided by setting B<copy_extensions> to B<copy> +and including basicConstraints with CA:FALSE in the configuration file. +Then if the request contains a basicConstraints extension it will be +ignored. + +It is advisable to also include values for other extensions such +as B<keyUsage> to prevent a request supplying its own values. + +Additional restrictions can be placed on the CA certificate itself. +For example if the CA certificate has: + + basicConstraints = CA:TRUE, pathlen:0 + +then even if a certificate is issued with CA:TRUE it will not be valid. + +=head1 SEE ALSO + +L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>, +L<config(5)>, L<x509v3_config(5)> + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/ciphers.pod b/openssl-1.1.0h/doc/apps/ciphers.pod new file mode 100644 index 0000000..def3bdc --- /dev/null +++ b/openssl-1.1.0h/doc/apps/ciphers.pod @@ -0,0 +1,731 @@ +=pod + +=head1 NAME + +openssl-ciphers, +ciphers - SSL cipher display and cipher list tool + +=head1 SYNOPSIS + +B<openssl> B<ciphers> +[B<-help>] +[B<-s>] +[B<-v>] +[B<-V>] +[B<-ssl3>] +[B<-tls1>] +[B<-tls1_1>] +[B<-tls1_2>] +[B<-s>] +[B<-psk>] +[B<-srp>] +[B<-stdname>] +[B<cipherlist>] + +=head1 DESCRIPTION + +The B<ciphers> command converts textual OpenSSL cipher lists into ordered +SSL cipher preference lists. It can be used as a test tool to determine +the appropriate cipherlist. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print a usage message. + +=item B<-s> + +Only list supported ciphers: those consistent with the security level, and +minimum and maximum protocol version. This is closer to the actual cipher list +an application will support. + +PSK and SRP ciphers are not enabled by default: they require B<-psk> or B<-srp> +to enable them. + +It also does not change the default list of supported signature algorithms. + +On a server the list of supported ciphers might also exclude other ciphers +depending on the configured certificates and presence of DH parameters. + +If this option is not used then all ciphers that match the cipherlist will be +listed. + +=item B<-psk> + +When combined with B<-s> includes cipher suites which require PSK. + +=item B<-srp> + +When combined with B<-s> includes cipher suites which require SRP. + +=item B<-v> + +Verbose output: For each ciphersuite, list details as provided by +L<SSL_CIPHER_description(3)>. + +=item B<-V> + +Like B<-v>, but include the official cipher suite values in hex. + +=item B<-tls1_2> + +In combination with the B<-s> option, list the ciphers which would be used if +TLSv1.2 were negotiated. + +=item B<-ssl3> + +In combination with the B<-s> option, list the ciphers which would be used if +SSLv3 were negotiated. + +=item B<-tls1> + +In combination with the B<-s> option, list the ciphers which would be used if +TLSv1 were negotiated. + +=item B<-tls1_1> + +In combination with the B<-s> option, list the ciphers which would be used if +TLSv1.1 were negotiated. + +=item B<-stdname> + +precede each ciphersuite by its standard name: only available is OpenSSL +is built with tracing enabled (B<enable-ssl-trace> argument to Configure). + +=item B<cipherlist> + +a cipher list to convert to a cipher preference list. If it is not included +then the default cipher list will be used. The format is described below. + +=back + +=head1 CIPHER LIST FORMAT + +The cipher list consists of one or more I<cipher strings> separated by colons. +Commas or spaces are also acceptable separators but colons are normally used. + +The actual cipher string can take several different forms. + +It can consist of a single cipher suite such as B<RC4-SHA>. + +It can represent a list of cipher suites containing a certain algorithm, or +cipher suites of a certain type. For example B<SHA1> represents all ciphers +suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3 +algorithms. + +Lists of cipher suites can be combined in a single cipher string using the +B<+> character. This is used as a logical B<and> operation. For example +B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES +algorithms. + +Each cipher string can be optionally preceded by the characters B<!>, +B<-> or B<+>. + +If B<!> is used then the ciphers are permanently deleted from the list. +The ciphers deleted can never reappear in the list even if they are +explicitly stated. + +If B<-> is used then the ciphers are deleted from the list, but some or +all of the ciphers can be added again by later options. + +If B<+> is used then the ciphers are moved to the end of the list. This +option doesn't add any new ciphers it just moves matching existing ones. + +If none of these characters is present then the string is just interpreted +as a list of ciphers to be appended to the current preference list. If the +list includes any ciphers already present they will be ignored: that is they +will not moved to the end of the list. + +The cipher string B<@STRENGTH> can be used at any point to sort the current +cipher list in order of encryption algorithm key length. + +The cipher string B<@SECLEVEL=n> can be used at any point to set the security +level to B<n>. + +=head1 CIPHER STRINGS + +The following is a list of all permitted cipher strings and their meanings. + +=over 4 + +=item B<DEFAULT> + +The default cipher list. +This is determined at compile time and is normally +B<ALL:!COMPLEMENTOFDEFAULT:!eNULL>. +When used, this must be the first cipherstring specified. + +=item B<COMPLEMENTOFDEFAULT> + +The ciphers included in B<ALL>, but not enabled by default. Currently +this includes all RC4 and anonymous ciphers. Note that this rule does +not cover B<eNULL>, which is not included by B<ALL> (use B<COMPLEMENTOFALL> if +necessary). Note that RC4 based ciphersuites are not built into OpenSSL by +default (see the enable-weak-ssl-ciphers option to Configure). + +=item B<ALL> + +All cipher suites except the B<eNULL> ciphers (which must be explicitly enabled +if needed). +As of OpenSSL 1.0.0, the B<ALL> cipher suites are sensibly ordered by default. + +=item B<COMPLEMENTOFALL> + +The cipher suites not enabled by B<ALL>, currently B<eNULL>. + +=item B<HIGH> + +"high" encryption cipher suites. This currently means those with key lengths +larger than 128 bits, and some cipher suites with 128-bit keys. + +=item B<MEDIUM> + +"medium" encryption cipher suites, currently some of those using 128 bit +encryption. + +=item B<LOW> + +"low" encryption cipher suites, currently those using 64 or 56 bit +encryption algorithms but excluding export cipher suites. All these +ciphersuites have been removed as of OpenSSL 1.1.0. + +=item B<eNULL>, B<NULL> + +The "NULL" ciphers that is those offering no encryption. Because these offer no +encryption at all and are a security risk they are not enabled via either the +B<DEFAULT> or B<ALL> cipher strings. +Be careful when building cipherlists out of lower-level primitives such as +B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers. When in +doubt, include B<!eNULL> in your cipherlist. + +=item B<aNULL> + +The cipher suites offering no authentication. This is currently the anonymous +DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable +to "man in the middle" attacks and so their use is discouraged. +These are excluded from the B<DEFAULT> ciphers, but included in the B<ALL> +ciphers. +Be careful when building cipherlists out of lower-level primitives such as +B<kDHE> or B<AES> as these do overlap with the B<aNULL> ciphers. +When in doubt, include B<!aNULL> in your cipherlist. + +=item B<kRSA>, B<aRSA>, B<RSA> + +Cipher suites using RSA key exchange or authentication. B<RSA> is an alias for +B<kRSA>. + +=item B<kDHr>, B<kDHd>, B<kDH> + +Cipher suites using static DH key agreement and DH certificates signed by CAs +with RSA and DSS keys or either respectively. +All these cipher suites have been removed in OpenSSL 1.1.0. + +=item B<kDHE>, B<kEDH>, B<DH> + +Cipher suites using ephemeral DH key agreement, including anonymous cipher +suites. + +=item B<DHE>, B<EDH> + +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<kEECDH>, B<kECDHE>, B<ECDH> + +Cipher suites using ephemeral ECDH key agreement, including anonymous +cipher suites. + +=item B<ECDHE>, B<EECDH> + +Cipher suites using authenticated ephemeral ECDH key agreement. + +=item B<AECDH> + +Anonymous Elliptic Curve Diffie-Hellman cipher suites. + +=item B<aDSS>, B<DSS> + +Cipher suites using DSS authentication, i.e. the certificates carry DSS keys. + +=item B<aDH> + +Cipher suites effectively using DH authentication, i.e. the certificates carry +DH keys. +All these cipher suites have been removed in OpenSSL 1.1.0. + +=item B<aECDSA>, B<ECDSA> + +Cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA +keys. + +=item B<TLSv1.2>, B<TLSv1.0>, B<SSLv3> + +Lists ciphersuites which are only supported in at least TLS v1.2, TLS v1.0 or +SSL v3.0 respectively. +Note: there are no ciphersuites specific to TLS v1.1. +Since this is only the minimum version, if, for example, TLSv1.0 is negotiated +then both TLSv1.0 and SSLv3.0 ciphersuites are available. + +Note: these cipher strings B<do not> change the negotiated version of SSL or +TLS, they only affect the list of available cipher suites. + +=item B<AES128>, B<AES256>, B<AES> + +cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES. + +=item B<AESGCM> + +AES in Galois Counter Mode (GCM): these ciphersuites are only supported +in TLS v1.2. + +=item B<AESCCM>, B<AESCCM8> + +AES in Cipher Block Chaining - Message Authentication Mode (CCM): these +ciphersuites are only supported in TLS v1.2. B<AESCCM> references CCM +cipher suites using both 16 and 8 octet Integrity Check Value (ICV) +while B<AESCCM8> only references 8 octet ICV. + +=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA> + +cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit +CAMELLIA. + +=item B<CHACHA20> + +cipher suites using ChaCha20. + +=item B<3DES> + +cipher suites using triple DES. + +=item B<DES> + +Cipher suites using DES (not triple DES). +All these cipher suites have been removed in OpenSSL 1.1.0. + +=item B<RC4> + +Cipher suites using RC4. + +=item B<RC2> + +Cipher suites using RC2. + +=item B<IDEA> + +Cipher suites using IDEA. + +=item B<SEED> + +Cipher suites using SEED. + +=item B<MD5> + +Cipher suites using MD5. + +=item B<SHA1>, B<SHA> + +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 authentication +(needs an engine supporting GOST algorithms). + +=item B<aGOST01> + +Cipher suites using GOST R 34.10-2001 authentication. + +=item B<kGOST> + +Cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357. + +=item B<GOST94> + +Cipher suites, using HMAC based on GOST R 34.11-94. + +=item B<GOST89MAC> + +Cipher suites using GOST 28147-89 MAC B<instead of> HMAC. + +=item B<PSK> + +All cipher suites using pre-shared keys (PSK). + +=item B<kPSK>, B<kECDHEPSK>, B<kDHEPSK>, B<kRSAPSK> + +Cipher suites using PSK key exchange, ECDHE_PSK, DHE_PSK or RSA_PSK. + +=item B<aPSK> + +Cipher suites using PSK authentication (currently all PSK modes apart from +RSA_PSK). + +=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192> + +Enables suite B mode of operation using 128 (permitting 192 bit mode by peer) +128 bit (not permitting 192 bit by peer) or 192 bit level of security +respectively. +If used these cipherstrings should appear first in the cipher +list and anything after them is ignored. +Setting Suite B mode has additional consequences required to comply with +RFC6460. +In particular the supported signature algorithms is reduced to support only +ECDSA and SHA256 or SHA384, only the elliptic curves P-256 and P-384 can be +used and only the two suite B compliant ciphersuites +(ECDHE-ECDSA-AES128-GCM-SHA256 and ECDHE-ECDSA-AES256-GCM-SHA384) are +permissible. + +=back + +=head1 CIPHER SUITE NAMES + +The following lists give the SSL or TLS cipher suites names from the +relevant specification and their OpenSSL equivalents. It should be noted, +that several cipher suite names do not include the authentication used, +e.g. DES-CBC3-SHA. In these cases, RSA authentication is used. + +=head2 SSL v3.0 cipher suites + + SSL_RSA_WITH_NULL_MD5 NULL-MD5 + SSL_RSA_WITH_NULL_SHA NULL-SHA + SSL_RSA_WITH_RC4_128_MD5 RC4-MD5 + SSL_RSA_WITH_RC4_128_SHA RC4-SHA + SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA + SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA + + SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA + SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-RSA-DES-CBC3-SHA + SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA + SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA + + SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 + SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA + + SSL_FORTEZZA_KEA_WITH_NULL_SHA Not implemented. + SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA Not implemented. + SSL_FORTEZZA_KEA_WITH_RC4_128_SHA Not implemented. + +=head2 TLS v1.0 cipher suites + + TLS_RSA_WITH_NULL_MD5 NULL-MD5 + TLS_RSA_WITH_NULL_SHA NULL-SHA + TLS_RSA_WITH_RC4_128_MD5 RC4-MD5 + TLS_RSA_WITH_RC4_128_SHA RC4-SHA + TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA + TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA + + TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented. + TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented. + TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA + TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA + + TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 + TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA + +=head2 AES ciphersuites from RFC3268, extending TLS v1.0 + + TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA + TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA + + TLS_DH_DSS_WITH_AES_128_CBC_SHA DH-DSS-AES128-SHA + TLS_DH_DSS_WITH_AES_256_CBC_SHA DH-DSS-AES256-SHA + TLS_DH_RSA_WITH_AES_128_CBC_SHA DH-RSA-AES128-SHA + TLS_DH_RSA_WITH_AES_256_CBC_SHA DH-RSA-AES256-SHA + + TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE-DSS-AES128-SHA + TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-DSS-AES256-SHA + TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE-RSA-AES128-SHA + TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA + + TLS_DH_anon_WITH_AES_128_CBC_SHA ADH-AES128-SHA + TLS_DH_anon_WITH_AES_256_CBC_SHA ADH-AES256-SHA + +=head2 Camellia ciphersuites from RFC4132, extending TLS v1.0 + + TLS_RSA_WITH_CAMELLIA_128_CBC_SHA CAMELLIA128-SHA + TLS_RSA_WITH_CAMELLIA_256_CBC_SHA CAMELLIA256-SHA + + TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA DH-DSS-CAMELLIA128-SHA + TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA DH-DSS-CAMELLIA256-SHA + TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA DH-RSA-CAMELLIA128-SHA + TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA DH-RSA-CAMELLIA256-SHA + + TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA DHE-DSS-CAMELLIA128-SHA + TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA DHE-DSS-CAMELLIA256-SHA + TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA DHE-RSA-CAMELLIA128-SHA + TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA DHE-RSA-CAMELLIA256-SHA + + TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA ADH-CAMELLIA128-SHA + TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA ADH-CAMELLIA256-SHA + +=head2 SEED ciphersuites from RFC4162, extending TLS v1.0 + + TLS_RSA_WITH_SEED_CBC_SHA SEED-SHA + + TLS_DH_DSS_WITH_SEED_CBC_SHA DH-DSS-SEED-SHA + TLS_DH_RSA_WITH_SEED_CBC_SHA DH-RSA-SEED-SHA + + TLS_DHE_DSS_WITH_SEED_CBC_SHA DHE-DSS-SEED-SHA + TLS_DHE_RSA_WITH_SEED_CBC_SHA DHE-RSA-SEED-SHA + + TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-SHA + +=head2 GOST ciphersuites from draft-chudov-cryptopro-cptls, extending TLS v1.0 + +Note: these ciphers require an engine which including GOST cryptographic +algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution. + + TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89 + TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89 + TLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94 + TLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94 + +=head2 Additional Export 1024 and other cipher suites + +Note: these ciphers can also be used in SSL v3. + + TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA + +=head2 Elliptic curve cipher suites. + + 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 DH-RSA-AES128-SHA256 + TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH-RSA-AES256-SHA256 + TLS_DH_RSA_WITH_AES_128_GCM_SHA256 DH-RSA-AES128-GCM-SHA256 + TLS_DH_RSA_WITH_AES_256_GCM_SHA384 DH-RSA-AES256-GCM-SHA384 + + TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH-DSS-AES128-SHA256 + TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH-DSS-AES256-SHA256 + TLS_DH_DSS_WITH_AES_128_GCM_SHA256 DH-DSS-AES128-GCM-SHA256 + TLS_DH_DSS_WITH_AES_256_GCM_SHA384 DH-DSS-AES256-GCM-SHA384 + + 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_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 + + RSA_WITH_AES_128_CCM AES128-CCM + RSA_WITH_AES_256_CCM AES256-CCM + DHE_RSA_WITH_AES_128_CCM DHE-RSA-AES128-CCM + DHE_RSA_WITH_AES_256_CCM DHE-RSA-AES256-CCM + RSA_WITH_AES_128_CCM_8 AES128-CCM8 + RSA_WITH_AES_256_CCM_8 AES256-CCM8 + DHE_RSA_WITH_AES_128_CCM_8 DHE-RSA-AES128-CCM8 + DHE_RSA_WITH_AES_256_CCM_8 DHE-RSA-AES256-CCM8 + ECDHE_ECDSA_WITH_AES_128_CCM ECDHE-ECDSA-AES128-CCM + ECDHE_ECDSA_WITH_AES_256_CCM ECDHE-ECDSA-AES256-CCM + ECDHE_ECDSA_WITH_AES_128_CCM_8 ECDHE-ECDSA-AES128-CCM8 + ECDHE_ECDSA_WITH_AES_256_CCM_8 ECDHE-ECDSA-AES256-CCM8 + +=head2 Camellia HMAC-Based ciphersuites from RFC6367, extending TLS v1.2 + + TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-ECDSA-CAMELLIA128-SHA256 + TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-ECDSA-CAMELLIA256-SHA384 + TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-RSA-CAMELLIA128-SHA256 + TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-RSA-CAMELLIA256-SHA384 + +=head2 Pre-shared keying (PSK) ciphersuites + + PSK_WITH_NULL_SHA PSK-NULL-SHA + DHE_PSK_WITH_NULL_SHA DHE-PSK-NULL-SHA + RSA_PSK_WITH_NULL_SHA RSA-PSK-NULL-SHA + + PSK_WITH_RC4_128_SHA PSK-RC4-SHA + PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA + PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA + PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA + + DHE_PSK_WITH_RC4_128_SHA DHE-PSK-RC4-SHA + DHE_PSK_WITH_3DES_EDE_CBC_SHA DHE-PSK-3DES-EDE-CBC-SHA + DHE_PSK_WITH_AES_128_CBC_SHA DHE-PSK-AES128-CBC-SHA + DHE_PSK_WITH_AES_256_CBC_SHA DHE-PSK-AES256-CBC-SHA + + RSA_PSK_WITH_RC4_128_SHA RSA-PSK-RC4-SHA + RSA_PSK_WITH_3DES_EDE_CBC_SHA RSA-PSK-3DES-EDE-CBC-SHA + RSA_PSK_WITH_AES_128_CBC_SHA RSA-PSK-AES128-CBC-SHA + RSA_PSK_WITH_AES_256_CBC_SHA RSA-PSK-AES256-CBC-SHA + + PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256 + PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384 + DHE_PSK_WITH_AES_128_GCM_SHA256 DHE-PSK-AES128-GCM-SHA256 + DHE_PSK_WITH_AES_256_GCM_SHA384 DHE-PSK-AES256-GCM-SHA384 + RSA_PSK_WITH_AES_128_GCM_SHA256 RSA-PSK-AES128-GCM-SHA256 + RSA_PSK_WITH_AES_256_GCM_SHA384 RSA-PSK-AES256-GCM-SHA384 + + PSK_WITH_AES_128_CBC_SHA256 PSK-AES128-CBC-SHA256 + PSK_WITH_AES_256_CBC_SHA384 PSK-AES256-CBC-SHA384 + PSK_WITH_NULL_SHA256 PSK-NULL-SHA256 + PSK_WITH_NULL_SHA384 PSK-NULL-SHA384 + DHE_PSK_WITH_AES_128_CBC_SHA256 DHE-PSK-AES128-CBC-SHA256 + DHE_PSK_WITH_AES_256_CBC_SHA384 DHE-PSK-AES256-CBC-SHA384 + DHE_PSK_WITH_NULL_SHA256 DHE-PSK-NULL-SHA256 + DHE_PSK_WITH_NULL_SHA384 DHE-PSK-NULL-SHA384 + RSA_PSK_WITH_AES_128_CBC_SHA256 RSA-PSK-AES128-CBC-SHA256 + RSA_PSK_WITH_AES_256_CBC_SHA384 RSA-PSK-AES256-CBC-SHA384 + RSA_PSK_WITH_NULL_SHA256 RSA-PSK-NULL-SHA256 + RSA_PSK_WITH_NULL_SHA384 RSA-PSK-NULL-SHA384 + PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256 + PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384 + + ECDHE_PSK_WITH_RC4_128_SHA ECDHE-PSK-RC4-SHA + ECDHE_PSK_WITH_3DES_EDE_CBC_SHA ECDHE-PSK-3DES-EDE-CBC-SHA + ECDHE_PSK_WITH_AES_128_CBC_SHA ECDHE-PSK-AES128-CBC-SHA + ECDHE_PSK_WITH_AES_256_CBC_SHA ECDHE-PSK-AES256-CBC-SHA + ECDHE_PSK_WITH_AES_128_CBC_SHA256 ECDHE-PSK-AES128-CBC-SHA256 + ECDHE_PSK_WITH_AES_256_CBC_SHA384 ECDHE-PSK-AES256-CBC-SHA384 + ECDHE_PSK_WITH_NULL_SHA ECDHE-PSK-NULL-SHA + ECDHE_PSK_WITH_NULL_SHA256 ECDHE-PSK-NULL-SHA256 + ECDHE_PSK_WITH_NULL_SHA384 ECDHE-PSK-NULL-SHA384 + + PSK_WITH_CAMELLIA_128_CBC_SHA256 PSK-CAMELLIA128-SHA256 + PSK_WITH_CAMELLIA_256_CBC_SHA384 PSK-CAMELLIA256-SHA384 + + DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 DHE-PSK-CAMELLIA128-SHA256 + DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 DHE-PSK-CAMELLIA256-SHA384 + + RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 RSA-PSK-CAMELLIA128-SHA256 + RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 RSA-PSK-CAMELLIA256-SHA384 + + ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-PSK-CAMELLIA128-SHA256 + ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-PSK-CAMELLIA256-SHA384 + + PSK_WITH_AES_128_CCM PSK-AES128-CCM + PSK_WITH_AES_256_CCM PSK-AES256-CCM + DHE_PSK_WITH_AES_128_CCM DHE-PSK-AES128-CCM + DHE_PSK_WITH_AES_256_CCM DHE-PSK-AES256-CCM + PSK_WITH_AES_128_CCM_8 PSK-AES128-CCM8 + PSK_WITH_AES_256_CCM_8 PSK-AES256-CCM8 + DHE_PSK_WITH_AES_128_CCM_8 DHE-PSK-AES128-CCM8 + DHE_PSK_WITH_AES_256_CCM_8 DHE-PSK-AES256-CCM8 + +=head2 ChaCha20-Poly1305 cipher suites, extending TLS v1.2 + + TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-RSA-CHACHA20-POLY1305 + TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-ECDSA-CHACHA20-POLY1305 + TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 DHE-RSA-CHACHA20-POLY1305 + TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 PSK-CHACHA20-POLY1305 + TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 ECDHE-PSK-CHACHA20-POLY1305 + TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 DHE-PSK-CHACHA20-POLY1305 + TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 RSA-PSK-CHACHA20-POLY1305 + +=head2 Older names used by OpenSSL + +The following names are accepted by older releases: + + SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA) + SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA) + +=head1 NOTES + +Some compiled versions of OpenSSL may not include all the ciphers +listed here because some ciphers were excluded at compile time. + +=head1 EXAMPLES + +Verbose listing of all OpenSSL ciphers including NULL ciphers: + + openssl ciphers -v 'ALL:eNULL' + +Include all ciphers except NULL and anonymous DH then sort by +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' + +Include all RC4 ciphers but leave out those without authentication: + + openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT' + +Include all ciphers with RSA authentication but leave out ciphers without +encryption. + + openssl ciphers -v 'RSA:!COMPLEMENTOFALL' + +Set security level to 2 and display all ciphers consistent with level 2: + + openssl ciphers -s -v 'ALL:@SECLEVEL=2' + +=head1 SEE ALSO + +L<s_client(1)>, L<s_server(1)>, L<ssl(7)> + +=head1 HISTORY + +The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/cms.pod b/openssl-1.1.0h/doc/apps/cms.pod new file mode 100644 index 0000000..96acd31 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/cms.pod @@ -0,0 +1,738 @@ +=pod + +=head1 NAME + +openssl-cms, +cms - CMS utility + +=head1 SYNOPSIS + +B<openssl> B<cms> +[B<-help>] +[B<-encrypt>] +[B<-decrypt>] +[B<-sign>] +[B<-verify>] +[B<-cmsout>] +[B<-resign>] +[B<-data_create>] +[B<-data_out>] +[B<-digest_create>] +[B<-digest_verify>] +[B<-compress>] +[B<-uncompress>] +[B<-EncryptedData_encrypt>] +[B<-sign_receipt>] +[B<-verify_receipt receipt>] +[B<-in filename>] +[B<-inform SMIME|PEM|DER>] +[B<-rctform SMIME|PEM|DER>] +[B<-out filename>] +[B<-outform SMIME|PEM|DER>] +[B<-stream -indef -noindef>] +[B<-noindef>] +[B<-content filename>] +[B<-text>] +[B<-noout>] +[B<-print>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-no_check_time>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level num>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-md digest>] +[B<-[cipher]>] +[B<-nointern>] +[B<-no_signer_cert_verify>] +[B<-nocerts>] +[B<-noattr>] +[B<-nosmimecap>] +[B<-binary>] +[B<-crlfeol>] +[B<-asciicrlf>] +[B<-nodetach>] +[B<-certfile file>] +[B<-certsout file>] +[B<-signer file>] +[B<-recip file>] +[B<-keyid>] +[B<-receipt_request_all -receipt_request_first>] +[B<-receipt_request_from emailaddress>] +[B<-receipt_request_to emailaddress>] +[B<-receipt_request_print>] +[B<-secretkey key>] +[B<-secretkeyid id>] +[B<-econtent_type type>] +[B<-inkey file>] +[B<-keyopt name:parameter>] +[B<-passin arg>] +[B<-rand file(s)>] +[B<cert.pem...>] +[B<-to addr>] +[B<-from addr>] +[B<-subject subj>] +[cert.pem]... + +=head1 DESCRIPTION + +The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and +verify, compress and uncompress S/MIME messages. + +=head1 OPTIONS + +There are fourteen operation options that set the type of operation to be +performed. The meaning of the other options varies according to the operation +type. + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-encrypt> + +encrypt mail for the given recipient certificates. Input file is the message +to be encrypted. The output file is the encrypted mail in MIME format. The +actual CMS type is <B>EnvelopedData<B>. + +Note that no revocation check is done for the recipient cert, so if that +key has been compromised, others may be able to decrypt the text. + +=item B<-decrypt> + +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 +the message to be signed. The signed message in MIME format is written +to the output file. + +=item B<-verify> + +verify signed mail. Expects a signed mail message on input and outputs +the signed data. Both clear text and opaque signing is supported. + +=item B<-cmsout> + +takes an input message and writes out a PEM encoded CMS structure. + +=item B<-resign> + +resign a message: take an existing message and one or more new signers. + +=item B<-data_create> + +Create a CMS B<Data> type. + +=item B<-data_out> + +B<Data> type and output the content. + +=item B<-digest_create> + +Create a CMS B<DigestedData> type. + +=item B<-digest_verify> + +Verify a CMS B<DigestedData> type and output the content. + +=item B<-compress> + +Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib> +support for this option to work, otherwise it will output an error. + +=item B<-uncompress> + +Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be +compiled with B<zlib> support for this option to work, otherwise it will +output an error. + +=item B<-EncryptedData_encrypt> + +Encrypt content using supplied symmetric key and algorithm using a CMS +B<EncryptedData> type and output the content. + +=item B<-sign_receipt> + +Generate and output a signed receipt for the supplied message. The input +message B<must> contain a signed receipt request. Functionality is otherwise +similar to the B<-sign> operation. + +=item B<-verify_receipt receipt> + +Verify a signed receipt in filename B<receipt>. The input message B<must> +contain the original receipt request. Functionality is otherwise similar +to the B<-verify> operation. + +=item B<-in filename> + +the input message to be encrypted or signed or the message to be decrypted +or verified. + +=item B<-inform SMIME|PEM|DER> + +this specifies the input format for the CMS structure. The default +is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> +format change this to expect PEM and DER format CMS structures +instead. This currently only affects the input format of the CMS +structure, if no CMS structure is being input (for example with +B<-encrypt> or B<-sign>) this option has no effect. + +=item B<-rctform SMIME|PEM|DER> + +specify the format for a signed receipt for use with the B<-receipt_verify> +operation. + +=item B<-out filename> + +the message text that has been decrypted or verified or the output MIME +format message that has been signed or verified. + +=item B<-outform SMIME|PEM|DER> + +this specifies the output format for the CMS structure. The default +is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER> +format change this to write PEM and DER format CMS structures +instead. This currently only affects the output format of the CMS +structure, if no CMS structure is being output (for example with +B<-verify> or B<-decrypt>) this option has no effect. + +=item B<-stream -indef -noindef> + +the B<-stream> and B<-indef> options are equivalent and enable streaming I/O +for encoding operations. This permits single pass processing of data without +the need to hold the entire contents in memory, potentially supporting very +large files. Streaming is automatically set for S/MIME signing with detached +data if the output format is B<SMIME> it is currently off by default for all +other operations. + +=item B<-noindef> + +disable streaming I/O where it would produce and indefinite length constructed +encoding. This option currently has no effect. In future streaming will be +enabled by default on all relevant operations and this option will disable it. + +=item B<-content filename> + +This specifies a file containing the detached content, this is only +useful with the B<-verify> command. This is only usable if the CMS +structure is using the detached signature form where the content is +not included. This option will override any content if the input format +is S/MIME and it uses the multipart/signed MIME content type. + +=item B<-text> + +this option adds plain text (text/plain) MIME headers to the supplied +message if encrypting or signing. If decrypting or verifying it strips +off text headers: if the decrypted or verified message is not of MIME +type text/plain then an error occurs. + +=item B<-noout> + +for the B<-cmsout> operation do not output the parsed CMS structure. This +is useful when combined with the B<-print> option or if the syntax of the CMS +structure is being checked. + +=item B<-print> + +for the B<-cmsout> operation print out all fields of the CMS structure. This +is mainly useful for testing purposes. + +=item B<-CAfile file> + +a file containing trusted CA certificates, only used with B<-verify>. + +=item B<-CApath dir> + +a directory containing trusted CA certificates, only used with +B<-verify>. This directory must be a standard certificate directory: that +is a hash of each subject name (using B<x509 -hash>) should be linked +to each certificate. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-md digest> + +digest algorithm to use when signing or resigning. If not present then the +default digest algorithm for the signing key will be used (usually SHA1). + +=item B<-[cipher]> + +the encryption algorithm to use. For example triple DES (168 bits) - B<-des3> +or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the +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 a list of ciphers +supported by your version of OpenSSL. + +If not specified triple DES is used. Only used with B<-encrypt> and +B<-EncryptedData_create> commands. + +=item B<-nointern> + +when verifying a message normally certificates (if any) included in +the message are searched for the signing certificate. With this option +only the certificates specified in the B<-certfile> option are used. +The supplied certificates can still be used as untrusted CAs however. + +=item B<-no_signer_cert_verify> + +do not verify the signers certificate of a signed message. + +=item B<-nocerts> + +when signing a message the signer's certificate is normally included +with this option it is excluded. This will reduce the size of the +signed message but the verifier must have a copy of the signers certificate +available locally (passed using the B<-certfile> option for example). + +=item B<-noattr> + +normally when a message is signed a set of attributes are included which +include the signing time and supported symmetric algorithms. With this +option they are not included. + +=item B<-nosmimecap> + +exclude the list of supported algorithms from signed attributes, other options +such as signing time and content type are still included. + +=item B<-binary> + +normally the input message is converted to "canonical" format which is +effectively using CR and LF as end of line: as required by the S/MIME +specification. When this option is present no translation occurs. This +is useful when handling binary data which may not be in MIME format. + +=item B<-crlfeol> + +normally the output file uses a single B<LF> as end of line. When this +option is present B<CRLF> is used instead. + +=item B<-asciicrlf> + +when signing use ASCII CRLF format canonicalisation. This strips trailing +whitespace from all lines, deletes trailing blank lines at EOF and sets +the encapsulated content type. This option is normally used with detached +content and an output signature format of DER. This option is not normally +needed when verifying as it is enabled automatically if the encapsulated +content format is detected. + +=item B<-nodetach> + +when signing a message use opaque signing: this form is more resistant +to translation by mail relays but it cannot be read by mail agents that +do not support S/MIME. Without this option cleartext signing with +the MIME type multipart/signed is used. + +=item B<-certfile file> + +allows additional certificates to be specified. When signing these will +be included with the message. When verifying these will be searched for +the signers certificates. The certificates should be in PEM format. + +=item B<-certsout file> + +any certificates contained in the message are written to B<file>. + +=item B<-signer file> + +a signing certificate when signing or resigning a message, this option can be +used multiple times if more than one signer is required. If a message is being +verified then the signers certificates will be written to this file if the +verification was successful. + +=item B<-recip file> + +when decrypting a message this specifies the recipients certificate. The +certificate must match one of the recipients of the message or an error +occurs. + +When encrypting a message this option may be used multiple times to specify +each recipient. This form B<must> be used if customised parameters are +required (for example to specify RSA-OAEP). + +=item B<-keyid> + +use subject key identifier to identify certificates instead of issuer name and +serial number. The supplied certificate B<must> include a subject key +identifier extension. Supported by B<-sign> and B<-encrypt> options. + +=item B<-receipt_request_all -receipt_request_first> + +for B<-sign> option include a signed receipt request. Indicate requests should +be provided by all recipient or first tier recipients (those mailed directly +and not from a mailing list). Ignored it B<-receipt_request_from> is included. + +=item B<-receipt_request_from emailaddress> + +for B<-sign> option include a signed receipt request. Add an explicit email +address where receipts should be supplied. + +=item B<-receipt_request_to emailaddress> + +Add an explicit email address where signed receipts should be sent to. This +option B<must> but supplied if a signed receipt it requested. + +=item B<-receipt_request_print> + +For the B<-verify> operation print out the contents of any signed receipt +requests. + +=item B<-secretkey key> + +specify symmetric key to use. The key must be supplied in hex format and be +consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt> +B<-EncryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used +with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the +content encryption key using an AES key in the B<KEKRecipientInfo> type. + +=item B<-secretkeyid id> + +the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type. +This option B<must> be present if the B<-secretkey> option is used with +B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the +relevant key if it is not supplied then an attempt is used to decrypt any +B<KEKRecipientInfo> structures. + +=item B<-econtent_type type> + +set the encapsulated content type to B<type> if not supplied the B<Data> type +is used. The B<type> argument can be any valid OID name in either text or +numerical format. + +=item B<-inkey file> + +the private key to use when signing or decrypting. This must match the +corresponding certificate. If this option is not specified then the +private key must be included in the certificate file specified with +the B<-recip> or B<-signer> file. When signing this option can be used +multiple times to specify successive keys. + +=item B<-keyopt name:opt> + +for signing and encryption this option can be used multiple times to +set customised parameters for the preceding key or certificate. It can +currently be used to set RSA-PSS for signing, RSA-OAEP for encryption +or to modify default parameters for ECDH. + +=item B<-passin arg> + +the private key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<cert.pem...> + +one or more certificates of message recipients: used when encrypting +a message. + +=item B<-to, -from, -subject> + +the relevant mail headers. These are included outside the signed +portion of a message so they may be included manually. If signing +then many S/MIME mail clients check the signers certificate's email +address matches that specified in the From: address. + +=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, +B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, +B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, +B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, +B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, +B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, +B<-verify_ip>, B<-verify_name>, B<-x509_strict> + +Set various certificate chain validation options. See the +L<verify(1)> manual page for details. + +=back + +=head1 NOTES + +The MIME message must be sent without any blank lines between the +headers and the output. Some mail programs will automatically add +a blank line. Piping the mail directly to sendmail is one way to +achieve the correct format. + +The supplied message to be signed or encrypted must include the +necessary MIME headers or many S/MIME clients won't display it +properly (if at all). You can use the B<-text> option to automatically +add plain text headers. + +A "signed and encrypted" message is one where a signed message is +then encrypted. This can be produced by encrypting an already signed +message: see the examples section. + +This version of the program only allows one signer per message but it +will verify multiple signers on received messages. Some S/MIME clients +choke if a message contains multiple signers. It is possible to sign +messages "in parallel" by signing an already signed message. + +The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME +clients. Strictly speaking these process CMS enveloped data: CMS +encrypted data is used for other purposes. + +The B<-resign> option uses an existing message digest when adding a new +signer. This means that attributes must be present in at least one existing +signer using the same message digest or this operation will fail. + +The B<-stream> and B<-indef> options enable streaming I/O support. +As a result the encoding is BER using indefinite length constructed encoding +and no longer DER. Streaming is supported for the B<-encrypt> operation and the +B<-sign> operation if the content is not detached. + +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)>). + +=head1 EXIT CODES + +=over 4 + +=item Z<>0 + +the operation was completely successfully. + +=item Z<>1 + +an error occurred parsing the command options. + +=item Z<>2 + +one of the input files could not be read. + +=item Z<>3 + +an error occurred creating the CMS file or when reading the MIME +message. + +=item Z<>4 + +an error occurred decrypting or verifying the message. + +=item Z<>5 + +the message was verified correctly but an error occurred writing out +the signers certificates. + +=back + +=head1 COMPATIBILITY WITH PKCS#7 format. + +The B<smime> utility can only process the older B<PKCS#7> format. The B<cms> +utility supports Cryptographic Message Syntax format. Use of some features +will result in messages which cannot be processed by applications which only +support the older format. These are detailed below. + +The use of the B<-keyid> option with B<-sign> or B<-encrypt>. + +The B<-outform PEM> option uses different headers. + +The B<-compress> option. + +The B<-secretkey> option when used with B<-encrypt>. + +The use of PSS with B<-sign>. + +The use of OAEP or non-RSA keys with B<-encrypt>. + +Additionally the B<-EncryptedData_create> and B<-data_create> type cannot +be processed by the older B<smime> command. + +=head1 EXAMPLES + +Create a cleartext signed message: + + openssl cms -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem + +Create an opaque signed message + + openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ + -signer mycert.pem + +Create a signed message, include some additional certificates and +read the private key from another file: + + openssl cms -sign -in in.txt -text -out mail.msg \ + -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem + +Create a signed message with two signers, use key identifier: + + openssl cms -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem -signer othercert.pem -keyid + +Send a signed message under Unix directly to sendmail, including headers: + + openssl cms -sign -in in.txt -text -signer mycert.pem \ + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed message" | sendmail someone@somewhere + +Verify a message and extract the signer's certificate if successful: + + openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt + +Send encrypted mail using triple DES: + + openssl cms -encrypt -in in.txt -from steve@openssl.org \ + -to someone@somewhere -subject "Encrypted message" \ + -des3 user.pem -out mail.msg + +Sign and encrypt mail: + + openssl cms -sign -in ml.txt -signer my.pem -text \ + | openssl cms -encrypt -out mail.msg \ + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed and Encrypted message" -des3 user.pem + +Note: the encryption command does not include the B<-text> option because the +message being encrypted already has MIME headers. + +Decrypt mail: + + openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem + +The output from Netscape form signing is a PKCS#7 structure with the +detached signature format. You can use this program to verify the +signature by line wrapping the base64 encoded structure and surrounding +it with: + + -----BEGIN PKCS7----- + -----END PKCS7----- + +and using the command, + + openssl cms -verify -inform PEM -in signature.pem -content content.txt + +alternatively you can base64 decode the signature and use + + openssl cms -verify -inform DER -in signature.der -content content.txt + +Create an encrypted message using 128 bit Camellia: + + openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem + +Add a signer to an existing message: + + openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg + +Sign mail using RSA-PSS: + + openssl cms -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem -keyopt rsa_padding_mode:pss + +Create encrypted mail using RSA-OAEP: + + openssl cms -encrypt -in plain.txt -out mail.msg \ + -recip cert.pem -keyopt rsa_padding_mode:oaep + +Use SHA256 KDF with an ECDH certificate: + + openssl cms -encrypt -in plain.txt -out mail.msg \ + -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256 + +=head1 BUGS + +The MIME parser isn't very clever: it seems to handle most messages that I've +thrown at it but it may choke on others. + +The code currently will only write out the signer's certificate to a file: if +the signer has a separate encryption certificate this must be manually +extracted. There should be some heuristic that determines the correct +encryption certificate. + +Ideally a database should be maintained of a certificates for each email +address. + +The code doesn't currently take note of the permitted symmetric encryption +algorithms as supplied in the SMIMECapabilities signed attribute. this means the +user has to manually include the correct encryption algorithm. It should store +the list of permitted ciphers in a database and only use those. + +No revocation checking is done on the signer's certificate. + +=head1 HISTORY + +The use of multiple B<-signer> options and the B<-resign> command were first +added in OpenSSL 1.0.0 + +The B<keyopt> option was first added in OpenSSL 1.1.0 + +The use of B<-recip> to specify the recipient when encrypting mail was first +added to OpenSSL 1.1.0 + +Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0. + +The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added +to OpenSSL 1.1.0. + +The -no_alt_chains options was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/config.pod b/openssl-1.1.0h/doc/apps/config.pod new file mode 100644 index 0000000..76f282f --- /dev/null +++ b/openssl-1.1.0h/doc/apps/config.pod @@ -0,0 +1,387 @@ +=pod + +=for comment openssl_manual_section:5 + +=head1 NAME + +config - OpenSSL CONF library configuration files + +=head1 DESCRIPTION + +The OpenSSL CONF library can be used to read configuration files. +It is used for the OpenSSL master configuration file B<openssl.cnf> +and in a few other places like B<SPKAC> files and certificate extension +files for the B<x509> utility. OpenSSL applications can also use the +CONF library for their own purposes. + +A configuration file is divided into a number of sections. Each section +starts with a line B<[ section_name ]> and ends when a new section is +started or end of file is reached. A section name can consist of +alphanumeric characters and underscores. + +The first section of a configuration file is special and is referred +to as the B<default> section this is usually unnamed and is from the +start of file until the first named section. When a name is being looked up +it is first looked up in a named section (if any) and then the +default section. + +The environment is mapped onto a section called B<ENV>. + +Comments can be included by preceding them with the B<#> character + +Each section in a configuration file consists of a number of name and +value pairs of the form B<name=value> + +The B<name> string can contain any alphanumeric characters as well as +a few punctuation symbols such as B<.> B<,> B<;> and B<_>. + +The B<value> string consists of the string following the B<=> character +until end of line with any leading and trailing white space removed. + +The value string undergoes variable expansion. This can be done by +including the form B<$var> or B<${var}>: this will substitute the value +of the named variable in the current section. It is also possible to +substitute a value from another section using the syntax B<$section::name> +or B<${section::name}>. By using the form B<$ENV::name> environment +variables can be substituted. It is also possible to assign values to +environment variables by using the name B<ENV::name>, this will work +if the program looks up environment variables using the B<CONF> library +instead of calling getenv() directly. The value string must not exceed 64k in +length after variable expansion. Otherwise an error will occur. + +It is possible to escape certain characters by using any kind of quote +or the B<\> character. By making the last character of a line a B<\> +a B<value> string can be spread across multiple lines. In addition +the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized. + +=head1 OPENSSL LIBRARY CONFIGURATION + +Applications can automatically configure certain +aspects of OpenSSL using the master OpenSSL configuration file, or optionally +an alternative configuration file. The B<openssl> utility includes this +functionality: any sub command uses the master OpenSSL configuration file +unless an option is used in the sub command to use an alternative configuration +file. + +To enable library configuration the default section needs to contain an +appropriate line which points to the main configuration section. The default +name is B<openssl_conf> which is used by the B<openssl> utility. Other +applications may use an alternative name such as B<myapplicaton_conf>. + +The configuration section should consist of a set of name value pairs which +contain specific module configuration information. The B<name> represents +the name of the I<configuration module> the meaning of the B<value> is +module specific: it may, for example, represent a further configuration +section containing configuration module specific information. E.g. + + openssl_conf = openssl_init + + [openssl_init] + + oid_section = new_oids + engines = engine_section + + [new_oids] + + ... new oids here ... + + [engine_section] + + ... engine stuff here ... + +The features of each configuration module are described below. + +=head2 ASN1 Object Configuration Module + +This module has the name B<oid_section>. The value of this variable points +to a section containing name value pairs of OIDs: the name is the OID short +and long name, the value is the numerical form of the OID. Although some of +the B<openssl> utility sub commands already have their own ASN1 OBJECT section +functionality not all do. By using the ASN1 OBJECT configuration module +B<all> the B<openssl> utility sub commands can see the new objects as well +as any compliant applications. For example: + + [new_oids] + + some_new_oid = 1.2.3.4 + some_other_oid = 1.2.3.5 + +It is also possible to set the value to the long name followed +by a comma and the numerical OID form. For example: + + shortName = some object long name, 1.2.3.4 + +=head2 Engine Configuration Module + +This ENGINE configuration module has the name B<engines>. The value of this +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 information +specific to each ENGINE. + +Each ENGINE specific section is used to set default algorithms, load +dynamic, perform initialization and send ctrls. The actual operation performed +depends on the I<command> name which is the name of the name value pair. The +currently supported commands are listed below. + +For example: + + [engine_section] + + # Configure ENGINE named "foo" + foo = foo_section + # Configure ENGINE named "bar" + bar = bar_section + + [foo_section] + ... foo ENGINE specific commands ... + + [bar_section] + ... "bar" ENGINE specific commands ... + +The command B<engine_id> is used to give the ENGINE name. If used this +command must be first. For example: + + [engine_section] + # This would normally handle an ENGINE named "foo" + foo = foo_section + + [foo_section] + # Override default name and use "myfoo" instead. + engine_id = myfoo + +The command B<dynamic_path> loads and adds an ENGINE from the given path. It +is equivalent to sending the ctrls B<SO_PATH> with the path argument followed +by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is +not the required behaviour then alternative ctrls can be sent directly +to the dynamic ENGINE using ctrl commands. + +The command B<init> determines whether to initialize the ENGINE. If the value +is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to +initialized the ENGINE immediately. If the B<init> command is not present +then an attempt will be made to initialize the ENGINE after all commands in +its section have been processed. + +The command B<default_algorithms> sets the default algorithms an ENGINE will +supply using the functions ENGINE_set_default_string(). + +If the name matches none of the above command names it is assumed to be a +ctrl command which is sent to the ENGINE. The value of the command is the +argument to the ctrl command. If the value is the string B<EMPTY> then no +value is sent to the command. + +For example: + + + [engine_section] + + # Configure ENGINE named "foo" + foo = foo_section + + [foo_section] + # Load engine from DSO + dynamic_path = /some/path/fooengine.so + # A foo specific ctrl. + some_ctrl = some_value + # Another ctrl that doesn't take a value. + other_ctrl = EMPTY + # Supply all default algorithms + default_algorithms = ALL + +=head2 EVP Configuration Module + +This modules has the name B<alg_section> which points to a section containing +algorithm commands. + +Currently the only algorithm command supported is B<fips_mode> whose +value should be a boolean string such as B<on> or B<off>. If the value is +B<on> this attempt to enter FIPS mode. If the call fails or the library is +not FIPS capable then an error occurs. + +For example: + + alg_section = evp_settings + + [evp_settings] + + fips_mode = on + +=head2 SSL Configuration Module + +This module has the name B<ssl_conf> which points to a section containing +SSL configurations. + +Each line in the SSL configuration section contains the name of the +configuration and the section containing it. + +Each configuration section consists of command value pairs for B<SSL_CONF>. +Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls +SSL_CTX_config() or SSL_config() with the appropriate configuration name. + +Note: any characters before an initial dot in the configuration section are +ignored so the same command can be used multiple times. + +For example: + + ssl_conf = ssl_sect + + [ssl_sect] + + server = server_section + + [server_section] + + RSA.Certificate = server-rsa.pem + ECDSA.Certificate = server-ecdsa.pem + Ciphers = ALL:!RC4 + +=head1 NOTES + +If a configuration file attempts to expand a variable that doesn't exist +then an error is flagged and the file will not load. This can happen +if an attempt is made to expand an environment variable that doesn't +exist. For example in a previous version of OpenSSL the default OpenSSL +master configuration file used the value of B<HOME> which may not be +defined on non Unix systems and would cause an error. + +This can be worked around by including a B<default> section to provide +a default value: then if the environment lookup fails the default value +will be used instead. For this to work properly the default value must +be defined earlier in the configuration file than the expansion. See +the B<EXAMPLES> section for an example of how to do this. + +If the same variable exists in the same section then all but the last +value will be silently ignored. In certain circumstances such as with +DNs the same field may occur multiple times. This is usually worked +around by ignoring any characters before an initial B<.> e.g. + + 1.OU="My first OU" + 2.OU="My Second OU" + +=head1 EXAMPLES + +Here is a sample configuration file using some of the features +mentioned above. + + # This is the default section. + + HOME=/temp + RANDFILE= ${ENV::HOME}/.rnd + configdir=$ENV::HOME/config + + [ section_one ] + + # We are now in section one. + + # Quotes permit leading and trailing whitespace + any = " any variable name " + + other = A string that can \ + cover several lines \ + by including \\ characters + + message = Hello World\n + + [ section_two ] + + greeting = $section_one::message + +This next example shows how to expand environment variables safely. + +Suppose you want a variable called B<tmpfile> to refer to a +temporary filename. The directory it is placed in can determined by +the B<TEMP> or B<TMP> environment variables but they may not be +set to any value at all. If you just include the environment variable +names and the variable doesn't exist then this will cause an error when +an attempt is made to load the configuration file. By making use of the +default section both values can be looked up with B<TEMP> taking +priority and B</tmp> used if neither is defined: + + TMP=/tmp + # The above value is used if TMP isn't in the environment + TEMP=$ENV::TMP + # The above value is used if TEMP isn't in the environment + tmpfile=${ENV::TEMP}/tmp.filename + +Simple OpenSSL library configuration example to enter FIPS mode: + + # Default appname: should match "appname" parameter (if any) + # supplied to CONF_modules_load_file et al. + openssl_conf = openssl_conf_section + + [openssl_conf_section] + # Configuration module list + alg_section = evp_sect + + [evp_sect] + # Set to "yes" to enter FIPS mode if supported + fips_mode = yes + +Note: in the above example you will get an error in non FIPS capable versions +of OpenSSL. + +More complex OpenSSL library configuration. Add OID and don't enter FIPS mode: + + # Default appname: should match "appname" parameter (if any) + # supplied to CONF_modules_load_file et al. + openssl_conf = openssl_conf_section + + [openssl_conf_section] + # Configuration module list + alg_section = evp_sect + oid_section = new_oids + + [evp_sect] + # This will have no effect as FIPS mode is off by default. + # Set to "yes" to enter FIPS mode, if supported + fips_mode = no + + [new_oids] + # New OID, just short name + newoid1 = 1.2.3.4.1 + # New OID shortname and long name + newoid2 = New OID 2 long name, 1.2.3.4.2 + +The above examples can be used with any application supporting library +configuration if "openssl_conf" is modified to match the appropriate "appname". + +For example if the second sample file above is saved to "example.cnf" then +the command line: + + OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1 + +will output: + + 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1 + +showing that the OID "newoid1" has been added as "1.2.3.4.1". + +=head1 BUGS + +Currently there is no way to include characters using the octal B<\nnn> +form. Strings are all null terminated so nulls cannot form part of +the value. + +The escaping isn't quite right: if you want to use sequences like B<\n> +you can't use any quote escaping on the same line. + +Files are loaded in a single pass. This means that an variable expansion +will only work if the variables referenced are defined earlier in the +file. + +=head1 SEE ALSO + +L<x509(1)>, L<req(1)>, L<ca(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/crl.pod b/openssl-1.1.0h/doc/apps/crl.pod new file mode 100644 index 0000000..fded397 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/crl.pod @@ -0,0 +1,143 @@ +=pod + +=head1 NAME + +openssl-crl, +crl - CRL utility + +=head1 SYNOPSIS + +B<openssl> B<crl> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-text>] +[B<-in filename>] +[B<-out filename>] +[B<-nameopt option>] +[B<-noout>] +[B<-hash>] +[B<-issuer>] +[B<-lastupdate>] +[B<-nextupdate>] +[B<-CAfile file>] +[B<-CApath dir>] + +=head1 DESCRIPTION + +The B<crl> command processes CRL files in DER or PEM format. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. B<DER> format is DER encoded CRL +structure. B<PEM> (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read from or standard input if this +option is not specified. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-text> + +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)>. + +=item B<-noout> + +don't output the encoded version of the CRL. + +=item B<-hash> + +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. + +=item B<-lastupdate> + +output the lastUpdate field. + +=item B<-nextupdate> + +output the nextUpdate field. + +=item B<-CAfile file> + +verify the signature on a CRL by looking up the issuing certificate in +B<file> + +=item B<-CApath dir> + +verify the signature on a CRL by looking up the issuing certificate in +B<dir>. This directory must be a standard certificate directory: that +is a hash of each subject name (using B<x509 -hash>) should be linked +to each certificate. + +=back + +=head1 NOTES + +The PEM CRL format uses the header and footer lines: + + -----BEGIN X509 CRL----- + -----END X509 CRL----- + +=head1 EXAMPLES + +Convert a CRL file from PEM to DER: + + openssl crl -in crl.pem -outform DER -out crl.der + +Output the text form of a DER encoded certificate: + + openssl crl -in crl.der -text -noout + +=head1 BUGS + +Ideally it should be possible to create a CRL using appropriate options +and files too. + +=head1 SEE ALSO + +L<crl2pkcs7(1)>, L<ca(1)>, L<x509(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/crl2pkcs7.pod b/openssl-1.1.0h/doc/apps/crl2pkcs7.pod new file mode 100644 index 0000000..933750a --- /dev/null +++ b/openssl-1.1.0h/doc/apps/crl2pkcs7.pod @@ -0,0 +1,106 @@ +=pod + +=head1 NAME + +openssl-crl2pkcs7, +crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates + +=head1 SYNOPSIS + +B<openssl> B<crl2pkcs7> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-certfile filename>] +[B<-nocrl>] + +=head1 DESCRIPTION + +The B<crl2pkcs7> command takes an optional CRL and one or more +certificates and converts them into a PKCS#7 degenerate "certificates +only" structure. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the CRL input format. B<DER> format is DER encoded CRL +structure.B<PEM> (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the PKCS#7 structure output format. B<DER> format is DER +encoded PKCS#7 structure.B<PEM> (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=item B<-in filename> + +This specifies the input filename to read a CRL from or standard input if this +option is not specified. + +=item B<-out filename> + +specifies the output filename to write the PKCS#7 structure to or standard +output by default. + +=item B<-certfile filename> + +specifies a filename containing one or more certificates in B<PEM> format. +All certificates in the file will be added to the PKCS#7 structure. This +option can be used more than once to read certificates form multiple +files. + +=item B<-nocrl> + +normally a CRL is included in the output file. With this option no CRL is +included in the output file and a CRL is not read from the input file. + +=back + +=head1 EXAMPLES + +Create a PKCS#7 structure from a certificate and CRL: + + openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem + +Creates a PKCS#7 structure in DER format with no CRL from several +different certificates: + + openssl crl2pkcs7 -nocrl -certfile newcert.pem + -certfile demoCA/cacert.pem -outform DER -out p7.der + +=head1 NOTES + +The output file is a PKCS#7 signed data structure containing no signers and +just certificates and an optional CRL. + +This utility can be used to send certificates and CAs to Netscape as part of +the certificate enrollment process. This involves sending the DER encoded output +as MIME type application/x-x509-user-cert. + +The B<PEM> encoded form with the header and footer lines removed can be used to +install user certificates and CAs in MSIE using the Xenroll control. + +=head1 SEE ALSO + +L<pkcs7(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/dgst.pod b/openssl-1.1.0h/doc/apps/dgst.pod new file mode 100644 index 0000000..59919c3 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/dgst.pod @@ -0,0 +1,239 @@ +=pod + +=head1 NAME + +openssl-dgst, +dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md4, md5, blake2b, blake2s - message digests + +=head1 SYNOPSIS + +B<openssl> B<dgst> +[B<-help>] +[B<-I<digest>>] +[B<-c>] +[B<-d>] +[B<-hex>] +[B<-binary>] +[B<-r>] +[B<-out filename>] +[B<-sign filename>] +[B<-keyform arg>] +[B<-passin arg>] +[B<-verify filename>] +[B<-prverify filename>] +[B<-signature filename>] +[B<-hmac key>] +[B<-fips-fingerprint>] +[B<-engine id>] +[B<-engine_impl>] +[B<file...>] + +B<openssl> +[I<digest>] +[B<...>] + +=head1 DESCRIPTION + +The digest functions output the message digest of a supplied file or files +in hexadecimal. The digest functions also generate and verify digital +signatures using message digests. + +The generic name, B<dgst>, may be used with an option specifying the +algorithm to be used. +The default digest is I<sha256>. +A supported I<digest> name may also be used as the command name. +To see the list of supported algorithms, use the I<list --digest-commands> +command. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-I<digest>> + +Specifies name of a supported digest to be used. To see the list of +supported digests, use the command I<list --digest-commands>. + +=item B<-c> + +Print out the digest in two digit groups separated by colons, only relevant if +B<hex> format output is used. + +=item B<-d> + +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. 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<-out filename> + +Filename to output to, or standard output by default. + +=item B<-sign filename> + +Digitally sign the digest using the private key in "filename". + +=item B<-keyform arg> + +Specifies the key format to sign digest with. The DER, PEM, P12, +and ENGINE formats are supported. + +=item B<-sigopt nm:v> + +Pass options to the signature algorithm during sign or verify operations. +Names and values of these options are algorithm-specific. + +=item B<-passin arg> + +The private key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-verify filename> + +Verify the signature using the public key in "filename". +The output is either "Verification OK" or "Verification Failure". + +=item B<-prverify filename> + +Verify the signature using the private key in "filename". + +=item B<-signature filename> + +The actual signature to verify. + +=item B<-hmac key> + +Create a hashed MAC using "key". + +=item B<-mac alg> + +Create MAC (keyed Message Authentication Code). The most popular MAC +algorithm is HMAC (hash-based MAC), but there are other MAC algorithms +which are not based on hash, for instance B<gost-mac> algorithm, +supported by B<ccgost> engine. MAC keys and other options should be set +via B<-macopt> parameter. + +=item B<-macopt nm:v> + +Passes options to MAC algorithm, specified by B<-mac> key. +Following options are supported by both by B<HMAC> and B<gost-mac>: + +=over 4 + +=item B<key:string> + +Specifies MAC key as alphanumeric 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. + +=item B<hexkey:string> + +Specifies MAC key in hexadecimal form (two hex digits per byte). +Key length must conform to any restrictions of the MAC algorithm +for example exactly 32 chars for gost-mac. + +=back + +=item B<-rand file(s)> + +A file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-fips-fingerprint> + +Compute HMAC using a specific key for certain OpenSSL-FIPS operations. + +=item B<-engine id> + +Use engine B<id> for operations (including private key storage). +This engine is not used as source for digest algorithms, unless it is +also specified in the configuration file or B<-engine_impl> is also +specified. + +=item B<-engine_impl> + +When used with the B<-engine> option, it specifies to also use +engine B<id> for digest operations. + +=item B<file...> + +File or files to digest. If no files are specified then standard input is +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 mechanisms that are available will depend on the options +used when building OpenSSL. +The B<list digest-commands> command can be used to list them. + +New or agile applications should use probably use SHA-256. Other digests, +particularly SHA-1 and MD5, are still widely used for interoperating +with existing formats and protocols. + +When signing a file, 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 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. + +=head1 HISTORY + +The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0 +The FIPS-related options were removed in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/dhparam.pod b/openssl-1.1.0h/doc/apps/dhparam.pod new file mode 100644 index 0000000..52fc0df --- /dev/null +++ b/openssl-1.1.0h/doc/apps/dhparam.pod @@ -0,0 +1,160 @@ +=pod + +=head1 NAME + +openssl-dhparam, +dhparam - DH parameter manipulation and generation + +=head1 SYNOPSIS + +B<openssl dhparam> +[B<-help>] +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-in> I<filename>] +[B<-out> I<filename>] +[B<-dsaparam>] +[B<-check>] +[B<-noout>] +[B<-text>] +[B<-C>] +[B<-2>] +[B<-5>] +[B<-rand> I<file(s)>] +[B<-engine id>] +[I<numbits>] + +=head1 DESCRIPTION + +This command is used to manipulate DH parameter files. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option uses an ASN1 DER encoded +form compatible with the PKCS#3 DHparameter structure. The PEM form is the +default format: it consists of the B<DER> format base64 encoded with +additional header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in> I<filename> + +This specifies the input filename to read parameters from or standard input if +this option is not specified. + +=item B<-out> I<filename> + +This specifies the output filename parameters to. Standard output is used +if this option is not present. The output filename should B<not> be the same +as the input filename. + +=item B<-dsaparam> + +If this option is used, DSA rather than DH parameters are read or created; +they are converted to DH format. Otherwise, "strong" primes (such +that (p-1)/2 is also prime) will be used for DH parameter generation. + +DH parameter generation with the B<-dsaparam> option is much faster, +and the recommended exponent length is shorter, which makes DH key +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> + +Performs numerous checks to see if the supplied parameters are valid and +displays a warning if not. + +=item B<-2>, B<-5> + +The generator to use, either 2 or 5. If present then the +input file is ignored and parameters are generated instead. If not +present but B<numbits> is present, parameters are generated with the +default generator 2. + +=item B<-rand> I<file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item I<numbits> + +this option specifies that a parameter set should be generated of size +I<numbits>. It must be the last option. If this option is present then +the input file is ignored and parameters are generated instead. If +this option is not present but a generator (B<-2> or B<-5>) is +present, parameters are generated with a default length of 2048 bits. + +=item B<-noout> + +this option inhibits the output of the encoded version of the parameters. + +=item B<-text> + +this option prints out the DH parameters in human readable form. + +=item B<-C> + +this option converts the parameters into C code. The parameters can then +be loaded by calling the get_dhNNNN() function. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<dhparam> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 WARNINGS + +The program B<dhparam> combines the functionality of the programs B<dh> and +B<gendh> in previous versions of OpenSSL. The B<dh> and B<gendh> +programs are retained for now but may have different purposes in future +versions of OpenSSL. + +=head1 NOTES + +PEM format DH parameters use the header and footer lines: + + -----BEGIN DH PARAMETERS----- + -----END DH PARAMETERS----- + +OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42 +DH. + +This program manipulates DH parameters not keys. + +=head1 BUGS + +There should be a way to generate and manipulate DH keys. + +=head1 SEE ALSO + +L<dsaparam(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/dsa.pod b/openssl-1.1.0h/doc/apps/dsa.pod new file mode 100644 index 0000000..3735804 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/dsa.pod @@ -0,0 +1,179 @@ +=pod + +=head1 NAME + +openssl-dsa, +dsa - DSA key processing + +=head1 SYNOPSIS + +B<openssl> B<dsa> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[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>] +[B<-text>] +[B<-noout>] +[B<-modulus>] +[B<-pubin>] +[B<-pubout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<dsa> command processes DSA keys. They can be converted between various +forms and their components printed out. B<Note> This command uses the +traditional SSLeay compatible format for private key encryption: newer +applications should use the more secure PKCS#8 format using the B<pkcs8> + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option with a private key uses +an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of +version (currently zero), p, q, g, the public and private key components +respectively as ASN.1 INTEGERs. When used with a public key it uses a +SubjectPublicKeyInfo structure: it is an error if the key is not DSA. + +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. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read a key from or standard input if this +option is not specified. If the key is encrypted a pass phrase will be +prompted for. + +=item B<-passin arg> + +the input file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output by +is not specified. If any encryption options are set then a pass phrase will be +prompted for. The output filename should B<not> be the same as the input +filename. + +=item B<-passout arg> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> + +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 +setting the encryption options it can be use to add or change the pass phrase. +These options can only be used with PEM format output files. + +=item B<-text> + +prints out the public, private key components and parameters. + +=item B<-noout> + +this option prevents output of the encoded version of the key. + +=item B<-modulus> + +this option prints out the value of the public key component of the key. + +=item B<-pubin> + +by default a private key is read from the input file: with this option a +public key is read instead. + +=item B<-pubout> + +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<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<dsa> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 NOTES + +The PEM private key format uses the header and footer lines: + + -----BEGIN DSA PRIVATE KEY----- + -----END DSA PRIVATE KEY----- + +The PEM public key format uses the header and footer lines: + + -----BEGIN PUBLIC KEY----- + -----END PUBLIC KEY----- + +=head1 EXAMPLES + +To remove the pass phrase on a DSA private key: + + openssl dsa -in key.pem -out keyout.pem + +To encrypt a private key using triple DES: + + openssl dsa -in key.pem -des3 -out keyout.pem + +To convert a private key from PEM to DER format: + + openssl dsa -in key.pem -outform DER -out keyout.der + +To print out the components of a private key to standard output: + + openssl dsa -in key.pem -text -noout + +To just output the public part of a private key: + + openssl dsa -in key.pem -pubout -out pubkey.pem + +=head1 SEE ALSO + +L<dsaparam(1)>, L<gendsa(1)>, L<rsa(1)>, +L<genrsa(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/dsaparam.pod b/openssl-1.1.0h/doc/apps/dsaparam.pod new file mode 100644 index 0000000..0dfda66 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/dsaparam.pod @@ -0,0 +1,125 @@ +=pod + +=head1 NAME + +openssl-dsaparam, +dsaparam - DSA parameter manipulation and generation + +=head1 SYNOPSIS + +B<openssl dsaparam> +[B<-help>] +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-text>] +[B<-C>] +[B<-rand file(s)>] +[B<-genkey>] +[B<-engine id>] +[B<numbits>] + +=head1 DESCRIPTION + +This command is used to manipulate or generate DSA parameter files. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option uses an ASN1 DER encoded +form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting +of p, q and g respectively. The PEM form is the default format: it consists +of the B<DER> format base64 encoded with additional header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read parameters from or standard input if +this option is not specified. If the B<numbits> parameter is included then +this option will be ignored. + +=item B<-out filename> + +This specifies the output filename parameters to. Standard output is used +if this option is not present. The output filename should B<not> be the same +as the input filename. + +=item B<-noout> + +this option inhibits the output of the encoded version of the parameters. + +=item B<-text> + +this option prints out the DSA parameters in human readable form. + +=item B<-C> + +this option converts the parameters into C code. The parameters can then +be loaded by calling the get_dsaXXX() function. + +=item B<-genkey> + +this option will generate a DSA either using the specified or generated +parameters. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<numbits> + +this option specifies that a parameter set should be generated of size +B<numbits>. It must be the last option. If this option is included then +the input file (if any) is ignored. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<dsaparam> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 NOTES + +PEM format DSA parameters use the header and footer lines: + + -----BEGIN DSA PARAMETERS----- + -----END DSA PARAMETERS----- + +DSA parameter generation is a slow process and as a result the same set of +DSA parameters is often used to generate several distinct keys. + +=head1 SEE ALSO + +L<gendsa(1)>, L<dsa(1)>, L<genrsa(1)>, +L<rsa(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/ec.pod b/openssl-1.1.0h/doc/apps/ec.pod new file mode 100644 index 0000000..c06005d --- /dev/null +++ b/openssl-1.1.0h/doc/apps/ec.pod @@ -0,0 +1,207 @@ +=pod + +=head1 NAME + +openssl-ec, +ec - EC key processing + +=head1 SYNOPSIS + +B<openssl> B<ec> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-text>] +[B<-noout>] +[B<-param_out>] +[B<-pubin>] +[B<-pubout>] +[B<-conv_form arg>] +[B<-param_enc arg>] +[B<-no_public>] +[B<-check>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<ec> command processes EC keys. They can be converted between various +forms and their components printed out. B<Note> OpenSSL uses the +private key format specified in 'SEC 1: Elliptic Curve Cryptography' +(http://www.secg.org/). To convert an OpenSSL EC private key into the +PKCS#8 private key format use the B<pkcs8> command. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +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 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. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read a key from or standard input if this +option is not specified. If the key is encrypted a pass phrase will be +prompted for. + +=item B<-passin arg> + +the input file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output by +is not specified. If any encryption options are set then a pass phrase will be +prompted for. The output filename should B<not> be the same as the input +filename. + +=item B<-passout arg> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-des|-des3|-idea> + +These options encrypt the private key with the DES, triple DES, IDEA or +any other cipher supported by OpenSSL 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<ec> utility to read in an encrypted key with no +encryption option can be used to remove the pass phrase from a key, or by +setting the encryption options it can be use to add or change the pass phrase. +These options can only be used with PEM format output files. + +=item B<-text> + +prints out the public, private key components and parameters. + +=item B<-noout> + +this option prevents output of the encoded version of the key. + +=item B<-modulus> + +this option prints out the value of the public key component of the key. + +=item B<-pubin> + +by default a private key is read from the input file: with this option a +public key is read instead. + +=item B<-pubout> + +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<-conv_form> + +This specifies how the points on the elliptic curve are converted +into octet strings. Possible values are: B<compressed> (the default +value), B<uncompressed> and B<hybrid>. For more information regarding +the point conversion forms please read the X9.62 standard. +B<Note> Due to patent issues the B<compressed> option is disabled +by default for binary curves and can be enabled by defining +the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time. + +=item B<-param_enc arg> + +This specifies how the elliptic curve parameters are encoded. +Possible value are: B<named_curve>, i.e. the ec parameters are +specified by an OID, or B<explicit> where the ec parameters are +explicitly given (see RFC 3279 for the definition of the +EC parameters structures). The default value is B<named_curve>. +B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279, +is currently not implemented in OpenSSL. + +=item B<-no_public> + +This option omits the public key components from the private key output. + +=item B<-check> + +this option checks the consistency of an EC private or public key. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<ec> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 NOTES + +The PEM private key format uses the header and footer lines: + + -----BEGIN EC PRIVATE KEY----- + -----END EC PRIVATE KEY----- + +The PEM public key format uses the header and footer lines: + + -----BEGIN PUBLIC KEY----- + -----END PUBLIC KEY----- + +=head1 EXAMPLES + +To encrypt a private key using triple DES: + + openssl ec -in key.pem -des3 -out keyout.pem + +To convert a private key from PEM to DER format: + + openssl ec -in key.pem -outform DER -out keyout.der + +To print out the components of a private key to standard output: + + openssl ec -in key.pem -text -noout + +To just output the public part of a private key: + + openssl ec -in key.pem -pubout -out pubkey.pem + +To change the parameters encoding to B<explicit>: + + openssl ec -in key.pem -param_enc explicit -out keyout.pem + +To change the point conversion form to B<compressed>: + + openssl ec -in key.pem -conv_form compressed -out keyout.pem + +=head1 SEE ALSO + +L<ecparam(1)>, L<dsa(1)>, L<rsa(1)> + +=head1 COPYRIGHT + +Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/ecparam.pod b/openssl-1.1.0h/doc/apps/ecparam.pod new file mode 100644 index 0000000..69a2631 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/ecparam.pod @@ -0,0 +1,186 @@ +=pod + +=head1 NAME + +openssl-ecparam, +ecparam - EC parameter manipulation and generation + +=head1 SYNOPSIS + +B<openssl ecparam> +[B<-help>] +[B<-inform DER|PEM>] +[B<-outform DER|PEM>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-text>] +[B<-C>] +[B<-check>] +[B<-name arg>] +[B<-list_curves>] +[B<-conv_form arg>] +[B<-param_enc arg>] +[B<-no_seed>] +[B<-rand file(s)>] +[B<-genkey>] +[B<-engine id>] + +=head1 DESCRIPTION + +This command is used to manipulate or generate EC parameter files. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option uses an ASN.1 DER encoded +form compatible with RFC 3279 EcpkParameters. The PEM form is the default +format: it consists of the B<DER> format base64 encoded with additional +header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read parameters from or standard input if +this option is not specified. + +=item B<-out filename> + +This specifies the output filename parameters to. Standard output is used +if this option is not present. The output filename should B<not> be the same +as the input filename. + +=item B<-noout> + +This option inhibits the output of the encoded version of the parameters. + +=item B<-text> + +This option prints out the EC parameters in human readable form. + +=item B<-C> + +This option converts the EC parameters into C code. The parameters can then +be loaded by calling the get_ec_group_XXX() function. + +=item B<-check> + +Validate the elliptic curve parameters. + +=item B<-name arg> + +Use the EC parameters with the specified 'short' name. Use B<-list_curves> +to get a list of all currently implemented EC parameters. + +=item B<-list_curves> + +If this options is specified B<ecparam> will print out a list of all +currently implemented EC parameters names and exit. + +=item B<-conv_form> + +This specifies how the points on the elliptic curve are converted +into octet strings. Possible values are: B<compressed>, B<uncompressed> (the +default value) and B<hybrid>. For more information regarding +the point conversion forms please read the X9.62 standard. +B<Note> Due to patent issues the B<compressed> option is disabled +by default for binary curves and can be enabled by defining +the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time. + +=item B<-param_enc arg> + +This specifies how the elliptic curve parameters are encoded. +Possible value are: B<named_curve>, i.e. the ec parameters are +specified by an OID, or B<explicit> where the ec parameters are +explicitly given (see RFC 3279 for the definition of the +EC parameters structures). The default value is B<named_curve>. +B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279, +is currently not implemented in OpenSSL. + +=item B<-no_seed> + +This option inhibits that the 'seed' for the parameter generation +is included in the ECParameters structure (see RFC 3279). + +=item B<-genkey> + +This option will generate an EC private key using the specified parameters. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<ecparam> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 NOTES + +PEM format EC parameters use the header and footer lines: + + -----BEGIN EC PARAMETERS----- + -----END EC PARAMETERS----- + +OpenSSL is currently not able to generate new groups and therefore +B<ecparam> can only create EC parameters from known (named) curves. + +=head1 EXAMPLES + +To create EC parameters with the group 'prime192v1': + + openssl ecparam -out ec_param.pem -name prime192v1 + +To create EC parameters with explicit parameters: + + openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit + +To validate given EC parameters: + + openssl ecparam -in ec_param.pem -check + +To create EC parameters and a private key: + + openssl ecparam -out ec_key.pem -name prime192v1 -genkey + +To change the point encoding to 'compressed': + + openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed + +To print out the EC parameters to standard output: + + openssl ecparam -in ec_param.pem -noout -text + +=head1 SEE ALSO + +L<ec(1)>, L<dsaparam(1)> + +=head1 COPYRIGHT + +Copyright 2003-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/enc.pod b/openssl-1.1.0h/doc/apps/enc.pod new file mode 100644 index 0000000..6338d6c --- /dev/null +++ b/openssl-1.1.0h/doc/apps/enc.pod @@ -0,0 +1,354 @@ +=pod + +=head1 NAME + +openssl-enc, +enc - symmetric cipher routines + +=head1 SYNOPSIS + +B<openssl enc -ciphername> +[B<-help>] +[B<-ciphers>] +[B<-in filename>] +[B<-out filename>] +[B<-pass arg>] +[B<-e>] +[B<-d>] +[B<-a/-base64>] +[B<-A>] +[B<-k password>] +[B<-kfile filename>] +[B<-K key>] +[B<-iv IV>] +[B<-S salt>] +[B<-salt>] +[B<-nosalt>] +[B<-z>] +[B<-md digest>] +[B<-p>] +[B<-P>] +[B<-bufsize number>] +[B<-nopad>] +[B<-debug>] +[B<-none>] +[B<-engine id>] + +=head1 DESCRIPTION + +The symmetric cipher commands allow data to be encrypted or decrypted +using various block and stream ciphers using keys based on passwords +or explicitly provided. Base64 encoding or decoding can also be performed +either by itself or in addition to the encryption or decryption. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-ciphers> + +List all supported ciphers. + +=item B<-in filename> + +the input filename, standard input by default. + +=item B<-out filename> + +the output filename, standard output by default. + +=item B<-pass arg> + +the password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-e> + +encrypt the input data: this is the default. + +=item B<-d> + +decrypt the input data. + +=item B<-a> + +base64 process the data. This means that if encryption is taking place +the data is base64 encoded after encryption. If decryption is set then +the input data is base64 decoded before being decrypted. + +=item B<-base64> + +same as B<-a> + +=item B<-A> + +if the B<-a> option is set then base64 process the data on one line. + +=item B<-k password> + +the password to derive the key from. This is for compatibility with previous +versions of OpenSSL. Superseded by the B<-pass> argument. + +=item B<-kfile filename> + +read the password to derive the key from the first line of B<filename>. +This is for compatibility with previous versions of OpenSSL. Superseded by +the B<-pass> argument. + +=item B<-md digest> + +Use the specified digest to create the key from the passphrase. +The default algorithm is sha-256. + +=item B<-nosalt> + +don't use a salt in the key derivation routines. This option B<SHOULD NOT> be +used except for test purposes or compatibility with ancient versions of +OpenSSL. + +=item B<-salt> + +use salt (randomly generated or provide with B<-S> option) when +encrypting (this is the default). + +=item B<-S salt> + +the actual salt to use: this must be represented as a string of hex digits. + +=item B<-K key> + +the actual key to use: this must be represented as a string comprised only +of hex digits. If only the key is specified, the IV must additionally specified +using the B<-iv> option. When both a key and a password are specified, the +key given with the B<-K> option will be used and the IV generated from the +password will be taken. It probably does not make much sense to specify +both key and password. + +=item B<-iv IV> + +the actual IV to use: this must be represented as a string comprised only +of hex digits. When only the key is specified using the B<-K> option, the +IV must explicitly be defined. When a password is being specified using +one of the other options, the IV is generated from this password. + +=item B<-p> + +print out the key and IV used. + +=item B<-P> + +print out the key and IV used then immediately exit: don't do any encryption +or decryption. + +=item B<-bufsize number> + +set the buffer size for I/O + +=item B<-nopad> + +disable standard block padding + +=item B<-debug> + +debug the BIOs used for I/O. + +=item B<-z> + +Compress or decompress clear text using zlib before encryption or after +decryption. This option exists only if OpenSSL with compiled with zlib +or zlib-dynamic option. + +=item B<-none> + +Use NULL cipher (no encryption or decryption of input). + +=back + +=head1 NOTES + +The program can be called either as B<openssl ciphername> or +B<openssl enc -ciphername>. But the first form doesn't work with +engine-provided ciphers, because this form is processed before the +configuration file is read and any ENGINEs loaded. + +Engines which provide entirely new encryption algorithms (such as ccgost +engine which provides gost89 algorithm) should be configured in the +configuration file. Engines, specified in the command line using -engine +options can only be used for hardware-assisted implementations of +ciphers, which are supported by OpenSSL core or other engine, specified +in the configuration file. + +When enc command lists supported ciphers, ciphers provided by engines, +specified in the configuration files are listed too. + +A password will be prompted for to derive the key and IV if necessary. + +The B<-salt> option should B<ALWAYS> be used if the key is being derived +from a password unless you want compatibility with previous versions of +OpenSSL. + +Without the B<-salt> option it is possible to perform efficient dictionary +attacks on the password and to attack stream cipher encrypted data. The reason +for this is that without the salt the same password always generates the same +encryption key. When the salt is being used the first eight bytes of the +encrypted data are reserved for the salt: it is generated at random when +encrypting a file and read from the encrypted file when it is decrypted. + +Some of the ciphers do not have large keys and others have security +implications if not used correctly. A beginner is advised to just use +a strong block cipher in CBC mode such as bf or des3. + +All the block ciphers normally use PKCS#5 padding also known as standard block +padding: this allows a rudimentary integrity or password check to be +performed. However since the chance of random data passing the test is +better than 1 in 256 it isn't a very good test. + +If padding is disabled then the input data must be a multiple of the cipher +block length. + +All RC2 ciphers have the same key and effective key length. + +Blowfish and RC5 algorithms use a 128 bit key. + +=head1 SUPPORTED CIPHERS + +Note that some of these ciphers can be disabled at compile time +and some are available only if an appropriate engine is configured +in the configuration file. The output of the B<enc> command run with +unsupported options (for example B<openssl enc -help>) includes a +list of ciphers, supported by your version 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 + + bf-cbc Blowfish in CBC mode + bf Alias for bf-cbc + bf-cfb Blowfish in CFB mode + bf-ecb Blowfish in ECB mode + bf-ofb Blowfish in OFB mode + + cast-cbc CAST in CBC mode + cast Alias for cast-cbc + cast5-cbc CAST5 in CBC mode + cast5-cfb CAST5 in CFB mode + cast5-ecb CAST5 in ECB mode + cast5-ofb CAST5 in OFB mode + + des-cbc DES in CBC mode + des Alias for des-cbc + des-cfb DES in CBC mode + des-ofb DES in OFB mode + des-ecb DES in ECB mode + + des-ede-cbc Two key triple DES EDE in CBC mode + des-ede Two key triple DES EDE in ECB mode + des-ede-cfb Two key triple DES EDE in CFB mode + des-ede-ofb Two key triple DES EDE in OFB mode + + des-ede3-cbc Three key triple DES EDE in CBC mode + des-ede3 Three key triple DES EDE in ECB mode + des3 Alias for des-ede3-cbc + des-ede3-cfb Three key triple DES EDE CFB mode + des-ede3-ofb Three key triple DES EDE in OFB mode + + desx DESX algorithm. + + gost89 GOST 28147-89 in CFB mode (provided by ccgost engine) + gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine) + + idea-cbc IDEA algorithm in CBC mode + idea same as idea-cbc + idea-cfb IDEA in CFB mode + idea-ecb IDEA in ECB mode + idea-ofb IDEA in OFB mode + + rc2-cbc 128 bit RC2 in CBC mode + rc2 Alias for rc2-cbc + rc2-cfb 128 bit RC2 in CFB mode + rc2-ecb 128 bit RC2 in ECB mode + rc2-ofb 128 bit RC2 in OFB mode + rc2-64-cbc 64 bit RC2 in CBC mode + rc2-40-cbc 40 bit RC2 in CBC mode + + rc4 128 bit RC4 + rc4-64 64 bit RC4 + rc4-40 40 bit RC4 + + rc5-cbc RC5 cipher in CBC mode + rc5 Alias for rc5-cbc + rc5-cfb RC5 cipher in CFB mode + rc5-ecb RC5 cipher in ECB mode + rc5-ofb RC5 cipher in OFB mode + + aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode + aes[128|192|256] Alias for aes-[128|192|256]-cbc + aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode + aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode + aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode + aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode + aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode + +=head1 EXAMPLES + +Just base64 encode a binary file: + + openssl base64 -in file.bin -out file.b64 + +Decode the same file + + openssl base64 -d -in file.b64 -out file.bin + +Encrypt a file using triple DES in CBC mode using a prompted password: + + openssl des3 -salt -in file.txt -out file.des3 + +Decrypt a file using a supplied password: + + openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword + +Encrypt a file then base64 encode it (so it can be sent via mail for example) +using Blowfish in CBC mode: + + openssl bf -a -salt -in file.txt -out file.bf + +Base64 decode a file then decrypt it: + + openssl bf -d -salt -a -in file.bf -out file.txt + +Decrypt some data using a supplied 40 bit RC4 key: + + openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 + +=head1 BUGS + +The B<-A> option when used with large files doesn't work properly. + +There should be an option to allow an iteration count to be included. + +The B<enc> program only supports a fixed number of algorithms with +certain parameters. So if, for example, you want to use RC2 with a +76 bit key or RC4 with an 84 bit key you can't use this program. + +=head1 HISTORY + +The default digest was changed from MD5 to SHA256 in Openssl 1.1. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/engine.pod b/openssl-1.1.0h/doc/apps/engine.pod new file mode 100644 index 0000000..155cc62 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/engine.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +openssl-engine, +engine - load and query engines + +=head1 SYNOPSIS + +B<openssl engine> +[ I<engine...> ] +[B<-v>] +[B<-vv>] +[B<-vvv>] +[B<-vvv>] +[B<-vvv>] +[B<-c>] +[B<-t>] +[B<-tt>] +[B<-pre> I<command>] +[B<-post> I<command>] +[ I<engine...> ] + +=head1 DESCRIPTION + +The B<engine> command is used to query the status and capabilities +of the specified B<engine>'s. +Engines may be specified before and after all other command-line flags. +Only those specified are queried. + +=head1 OPTIONS + +=over 4 + +=item B<-v> B<-vv> B<-vvv> B<-vvvv> + +Provides information about each specified engine. The first flag lists +all the possible run-time control commands; the second adds a +description of each command; the third adds the input flags, and the +final option adds the internal input flags. + +=item B<-c> + +Lists the capabilities of each engine. + +=item B<-t> + +Tests if each specified engine is available, and displays the answer. + +=item B<-tt> + +Displays an error trace for any unavailable engine. + +=item B<-pre> I<command> + +=item B<-post> I<command> + +Command-line configuration of engines. +The B<-pre> command is given to the engine before it is loaded and +the B<-post> command is given after the engine is loaded. +The I<command> is of the form I<cmd:val> where I<cmd> is the command, +and I<val> is the value for the command. +See the example below. + +=back + +=head1 EXAMPLE + +To list all the commands available to a dynamic engine: + + % openssl engine -t -tt -vvvv dynamic + (dynamic) Dynamic engine loading support + [ unavailable ] + SO_PATH: Specifies the path to the new ENGINE shared library + (input flags): STRING + NO_VCHECK: Specifies to continue even if version checking fails (boolean) + (input flags): NUMERIC + ID: Specifies an ENGINE id name for loading + (input flags): STRING + LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory) + (input flags): NUMERIC + DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory) + (input flags): NUMERIC + DIR_ADD: Adds a directory from which ENGINEs can be loaded + (input flags): STRING + LOAD: Load up the ENGINE specified by other settings + (input flags): NO_INPUT + +To list the capabilities of the I<rsax> engine: + + % openssl engine -c + (rsax) RSAX engine support + [RSA] + (dynamic) Dynamic engine loading support + +=head1 ENVIRONMENT + +=over 4 + +=item B<OPENSSL_ENGINES> + +The path to the engines directory. + +=back + +=head1 COPYRIGHT + +Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/errstr.pod b/openssl-1.1.0h/doc/apps/errstr.pod new file mode 100644 index 0000000..3c89b8f --- /dev/null +++ b/openssl-1.1.0h/doc/apps/errstr.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +openssl-errstr, +errstr - lookup error codes + +=head1 SYNOPSIS + +B<openssl errstr error_code> + +=head1 DESCRIPTION + +Sometimes an application will not load error message and only +numerical forms will be available. The B<errstr> utility can be used to +display the meaning of the hex code. The hex code is the hex digits after the +second colon. + +=head1 OPTIONS + +None. + +=head1 EXAMPLE + +The error code: + + 27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107: + +can be displayed with: + + openssl errstr 2006D080 + +to produce the error message: + + error:2006D080:BIO routines:BIO_new_file:no such file + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/gendsa.pod b/openssl-1.1.0h/doc/apps/gendsa.pod new file mode 100644 index 0000000..36c810a --- /dev/null +++ b/openssl-1.1.0h/doc/apps/gendsa.pod @@ -0,0 +1,92 @@ +=pod + +=head1 NAME + +openssl-gendsa, +gendsa - generate a DSA private key from a set of parameters + +=head1 SYNOPSIS + +B<openssl> B<gendsa> +[B<-help>] +[B<-out filename>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-rand file(s)>] +[B<-engine id>] +[B<paramfile>] + +=head1 DESCRIPTION + +The B<gendsa> command generates a DSA private key from a DSA parameter file +(which will be typically generated by the B<openssl dsaparam> command). + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-out filename> + +Output the key to the specified file. If this argument is not specified then +standard output is used. + +=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> + +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)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<gendsa> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<paramfile> + +This option specifies the DSA parameter file to use. The parameters in this +file determine the size of the private key. DSA parameters can be generated +and examined using the B<openssl dsaparam> command. + +=back + +=head1 NOTES + +DSA key generation is little more than random number generation so it is +much quicker that RSA key generation for example. + +=head1 SEE ALSO + +L<dsaparam(1)>, L<dsa(1)>, L<genrsa(1)>, +L<rsa(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/genpkey.pod b/openssl-1.1.0h/doc/apps/genpkey.pod new file mode 100644 index 0000000..d486952 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/genpkey.pod @@ -0,0 +1,278 @@ +=pod + +=head1 NAME + +openssl-genpkey, +genpkey - generate a private key + +=head1 SYNOPSIS + +B<openssl> B<genpkey> +[B<-help>] +[B<-out filename>] +[B<-outform PEM|DER>] +[B<-pass arg>] +[B<-cipher>] +[B<-engine id>] +[B<-paramfile file>] +[B<-algorithm alg>] +[B<-pkeyopt opt:value>] +[B<-genparam>] +[B<-text>] + +=head1 DESCRIPTION + +The B<genpkey> command generates a private key. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-out filename> + +Output the key to the specified file. If this argument is not specified then +standard output is used. + +=item B<-outform DER|PEM> + +This specifies the output format DER or PEM. + +=item B<-pass arg> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-cipher> + +This option encrypts the private key with the supplied cipher. Any algorithm +name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<genpkey> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. If used this option should precede all other +options. + +=item B<-algorithm alg> + +public key algorithm to use such as RSA, DSA or DH. If used this option must +precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> +are mutually exclusive. + +=item B<-pkeyopt opt:value> + +set the public key algorithm option B<opt> to B<value>. The precise set of +options supported depends on the public key algorithm used and its +implementation. See B<KEY GENERATION OPTIONS> below for more details. + +=item B<-genparam> + +generate a set of parameters instead of a private key. If used this option must +precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options. + +=item B<-paramfile filename> + +Some public key algorithms generate a private key based on a set of parameters. +They can be supplied using this option. If this option is used the public key +algorithm used is determined by the parameters. If used this option must +precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm> +are mutually exclusive. + +=item B<-text> + +Print an (unencrypted) text representation of private and public keys and +parameters along with the PEM or DER structure. + +=back + +=head1 KEY GENERATION OPTIONS + +The options supported by each algorithm and indeed each implementation of an +algorithm can vary. The options for the OpenSSL implementations are detailed +below. + +=head1 RSA KEY GENERATION OPTIONS + +=over 4 + +=item B<rsa_keygen_bits:numbits> + +The number of bits in the generated key. If not specified 1024 is used. + +=item B<rsa_keygen_pubexp:value> + +The RSA public exponent value. This can be a large decimal or +hexadecimal value if preceded by B<0x>. Default value is 65537. + +=back + +=head1 DSA PARAMETER GENERATION OPTIONS + +=over 4 + +=item B<dsa_paramgen_bits:numbits> + +The number of bits in the generated parameters. If not specified 1024 is used. + +=back + +=head1 DH PARAMETER GENERATION OPTIONS + +=over 4 + +=item B<dh_paramgen_prime_len:numbits> + +The number of bits in the prime parameter B<p>. + +=item B<dh_paramgen_generator:value> + +The value to use for the generator B<g>. + +=item B<dh_rfc5114:num> + +If this option is set then the appropriate RFC5114 parameters are used +instead of generating new parameters. The value B<num> can take the +values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of +1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup +and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections +2.1, 2.2 and 2.3 respectively. + +=back + +=head1 EC PARAMETER GENERATION OPTIONS + +The EC parameter generation options below can also +be supplied as EC key generation options. This can (for example) generate a +key from a named curve without the need to use an explicit parameter file. + +=over 4 + +=item B<ec_paramgen_curve:curve> + +the EC curve to use. OpenSSL supports NIST curve names such as "P-256". + +=item B<ec_param_enc:encoding> + +the encoding to use for parameters. The "encoding" parameter must be either +"named_curve" or "explicit". + +=back + +=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS + +Gost 2001 support is not enabled by default. To enable this algorithm, +one should load the ccgost engine in the OpenSSL configuration file. +See README.gost file in the engines/ccgost directory of the source +distribution for more details. + +Use of a parameter file for the GOST R 34.10 algorithm is optional. +Parameters can be specified during key generation directly as well as +during generation of parameter file. + +=over 4 + +=item B<paramset:name> + +Specifies GOST R 34.10-2001 parameter set according to RFC 4357. +Parameter set can be specified using abbreviated name, object short name or +numeric OID. Following parameter sets are supported: + + paramset OID Usage + A 1.2.643.2.2.35.1 Signature + B 1.2.643.2.2.35.2 Signature + C 1.2.643.2.2.35.3 Signature + XA 1.2.643.2.2.36.0 Key exchange + XB 1.2.643.2.2.36.1 Key exchange + test 1.2.643.2.2.35.0 Test purposes + +=back + +=head1 X25519 KEY GENERATION OPTIONS + +The X25519 algorithm does not currently support any key generation options. + + +=head1 NOTES + +The use of the genpkey program is encouraged over the algorithm specific +utilities because additional algorithm options and ENGINE provided algorithms +can be used. + +=head1 EXAMPLES + +Generate an RSA private key using default parameters: + + openssl genpkey -algorithm RSA -out key.pem + +Encrypt output private key using 128 bit AES and the passphrase "hello": + + openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello + +Generate a 2048 bit RSA key using 3 as the public exponent: + + openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \ + -pkeyopt rsa_keygen_pubexp:3 + +Generate 1024 bit DSA parameters: + + openssl genpkey -genparam -algorithm DSA -out dsap.pem \ + -pkeyopt dsa_paramgen_bits:1024 + +Generate DSA key from parameters: + + openssl genpkey -paramfile dsap.pem -out dsakey.pem + +Generate 1024 bit DH parameters: + + openssl genpkey -genparam -algorithm DH -out dhp.pem \ + -pkeyopt dh_paramgen_prime_len:1024 + +Output RFC5114 2048 bit DH parameters with 224 bit subgroup: + + openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2 + +Generate DH key from parameters: + + openssl genpkey -paramfile dhp.pem -out dhkey.pem + +Generate EC parameters: + + openssl genpkey -genparam -algorithm EC -out ecp.pem \ + -pkeyopt ec_paramgen_curve:secp384r1 \ + -pkeyopt ec_param_enc:named_curve + +Generate EC key from parameters: + + openssl genpkey -paramfile ecp.pem -out eckey.pem + +Generate EC key directly: + + openssl genpkey -algorithm EC -out eckey.pem \ + -pkeyopt ec_paramgen_curve:P-384 \ + -pkeyopt ec_param_enc:named_curve + +Generate an X25519 private key: + + openssl genpkey -algorithm X25519 -out xkey.pem + +=head1 HISTORY + +The ability to use NIST curve names, and to generate an EC key directly, +were added in OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/genrsa.pod b/openssl-1.1.0h/doc/apps/genrsa.pod new file mode 100644 index 0000000..8be0683 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/genrsa.pod @@ -0,0 +1,119 @@ +=pod + +=head1 NAME + +openssl-genrsa, +genrsa - generate an RSA private key + +=head1 SYNOPSIS + +B<openssl> B<genrsa> +[B<-help>] +[B<-out filename>] +[B<-passout arg>] +[B<-aes128>] +[B<-aes192>] +[B<-aes256>] +[B<-aria128>] +[B<-aria192>] +[B<-aria256>] +[B<-camellia128>] +[B<-camellia192>] +[B<-camellia256>] +[B<-des>] +[B<-des3>] +[B<-idea>] +[B<-f4>] +[B<-3>] +[B<-rand file(s)>] +[B<-engine id>] +[B<numbits>] + +=head1 DESCRIPTION + +The B<genrsa> command generates an RSA private key. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-out filename> + +Output the key to the specified file. If this argument is not specified then +standard output is used. + +=item B<-passout arg> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-aes128|-aes192|-aes256|-aria128|-aria192|-aria256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> + +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. + +=item B<-F4|-3> + +the public exponent to use, either 65537 or 3. The default is 65537. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<genrsa> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<numbits> + +the size of the private key to generate in bits. This must be the last option +specified. The default is 2048. + +=back + +=head1 NOTES + +RSA private key generation essentially involves the generation of two prime +numbers. When generating a private key various symbols will be output to +indicate the progress of the generation. A B<.> represents each number which +has passed an initial sieve test, B<+> means a number has passed a single +round of the Miller-Rabin primality test. A newline means that the number has +passed all the prime tests (the actual number depends on the key size). + +Because key generation is a random process the time taken to generate a key +may vary somewhat. + +=head1 BUGS + +A quirk of the prime generation algorithm is that it cannot generate small +primes. Therefore the number of bits should not be less that 64. For typical +private keys this will not matter because for security reasons they will +be much larger (typically 1024 bits). + +=head1 SEE ALSO + +L<gendsa(1)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/list.pod b/openssl-1.1.0h/doc/apps/list.pod new file mode 100644 index 0000000..1088762 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/list.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +openssl-list, +list - list algorithms and features + +=head1 SYNOPSIS + +B<openssl list> +[B<-help>] +[B<-commands>] +[B<-digest-commands>] +[B<-digest-algorithms>] +[B<-cipher-commands>] +[B<-cipher-algorithms>] +[B<-public-key-algorithms>] +[B<-disabled>] + +=head1 DESCRIPTION + +This command is used to generate list of algorithms or disabled +features. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Display out a usage message. + +=item B<-commands> + +Display a list of standard commands. + +=item B<-digest-commands> + +Display a list of message digest commands, which are typically used +as input to the L<dgst(1)> or L<speed(1)> commands. + +=item B<-digest-algorithms> + +Display a list of message digest algorithms. +If a line is of the form + foo => bar +then B<foo> is an alias for the official algorithm name, B<bar>. + +=item B<-cipher-commands> + +Display a list of cipher commands, which are typically used as input +to the L<dgst(1)> or L<speed(1)> commands. + +=item B<-cipher-algorithms> + +Display a list of cipher algorithms. +If a line is of the form + foo => bar +then B<foo> is an alias for the official algorithm name, B<bar>. + +=item B<-public-key-algorithms> + +Display a list of public key algorithms, with each algorithm as +a block of multiple lines, all but the first are indented. + +=item B<-disabled> + +Display a list of disabled features, those that were compiled out +of the installation. + +=back + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/nseq.pod b/openssl-1.1.0h/doc/apps/nseq.pod new file mode 100644 index 0000000..6b25e22 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/nseq.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +openssl-nseq, +nseq - create or examine a Netscape certificate sequence + +=head1 SYNOPSIS + +B<openssl> B<nseq> +[B<-help>] +[B<-in filename>] +[B<-out filename>] +[B<-toseq>] + +=head1 DESCRIPTION + +The B<nseq> command takes a file containing a Netscape certificate +sequence and prints out the certificates contained in it or takes a +file of certificates and converts it into a Netscape certificate +sequence. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read or standard input if this +option is not specified. + +=item B<-out filename> + +specifies the output filename or standard output by default. + +=item B<-toseq> + +normally a Netscape certificate sequence will be input and the output +is the certificates contained in it. With the B<-toseq> option the +situation is reversed: a Netscape certificate sequence is created from +a file of certificates. + +=back + +=head1 EXAMPLES + +Output the certificates in a Netscape certificate sequence + + openssl nseq -in nseq.pem -out certs.pem + +Create a Netscape certificate sequence + + openssl nseq -in certs.pem -toseq -out nseq.pem + +=head1 NOTES + +The B<PEM> encoded form uses the same headers and footers as a certificate: + + -----BEGIN CERTIFICATE----- + -----END CERTIFICATE----- + +A Netscape certificate sequence is a Netscape specific form that can be sent +to browsers as an alternative to the standard PKCS#7 format when several +certificates are sent to the browser: for example during certificate enrollment. +It is used by Netscape certificate server for example. + +=head1 BUGS + +This program needs a few more options: like allowing DER or PEM input and +output files and allowing multiple certificate files to be used. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/ocsp.pod b/openssl-1.1.0h/doc/apps/ocsp.pod new file mode 100644 index 0000000..5e273cf --- /dev/null +++ b/openssl-1.1.0h/doc/apps/ocsp.pod @@ -0,0 +1,467 @@ +=pod + +=head1 NAME + +openssl-ocsp, +ocsp - Online Certificate Status Protocol utility + +=head1 SYNOPSIS + +B<openssl> B<ocsp> +[B<-help>] +[B<-out file>] +[B<-issuer file>] +[B<-cert file>] +[B<-serial n>] +[B<-signer file>] +[B<-signkey file>] +[B<-sign_other file>] +[B<-no_certs>] +[B<-req_text>] +[B<-resp_text>] +[B<-text>] +[B<-reqout file>] +[B<-respout file>] +[B<-reqin file>] +[B<-respin file>] +[B<-nonce>] +[B<-no_nonce>] +[B<-url URL>] +[B<-host host:port>] +[B<-header>] +[B<-path>] +[B<-CApath dir>] +[B<-CAfile file>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-no_check_time>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level num>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-VAfile file>] +[B<-validity_period n>] +[B<-status_age n>] +[B<-noverify>] +[B<-verify_other file>] +[B<-trust_other>] +[B<-no_intern>] +[B<-no_signature_verify>] +[B<-no_cert_verify>] +[B<-no_chain>] +[B<-no_cert_checks>] +[B<-no_explicit>] +[B<-port num>] +[B<-index file>] +[B<-CA file>] +[B<-rsigner file>] +[B<-rkey file>] +[B<-rother file>] +[B<-resp_no_certs>] +[B<-nmin n>] +[B<-ndays n>] +[B<-resp_key_id>] +[B<-nrequest n>] +[B<-md5|-sha1|...>] + +=head1 DESCRIPTION + +The Online Certificate Status Protocol (OCSP) enables applications to +determine the (revocation) state of an identified certificate (RFC 2560). + +The B<ocsp> command performs many common OCSP tasks. It can be used +to print out requests and responses, create requests and send queries +to an OCSP responder and behave like a mini OCSP server itself. + +=head1 OPTIONS + +This command operates as either a client or a server. +The options are described below, divided into those two modes. + +=head2 OCSP Client Options + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-out filename> + +specify output filename, default is standard output. + +=item B<-issuer filename> + +This specifies the current issuer certificate. This option can be used +multiple times. The certificate specified in B<filename> must be in +PEM format. This option B<MUST> come before any B<-cert> options. + +=item B<-cert filename> + +Add the certificate B<filename> to the request. The issuer certificate +is taken from the previous B<issuer> option, or an error occurs if no +issuer certificate is specified. + +=item B<-serial num> + +Same as the B<cert> option except the certificate with serial number +B<num> is added to the request. The serial number is interpreted as a +decimal integer unless preceded by B<0x>. Negative integers can also +be specified by preceding the value by a B<-> sign. + +=item B<-signer filename>, B<-signkey filename> + +Sign the OCSP request using the certificate specified in the B<signer> +option and the private key specified by the B<signkey> option. If +the B<signkey> option is not present then the private key is read +from the same file as the certificate. If neither option is specified then +the OCSP request is not signed. + +=item B<-sign_other filename> + +Additional certificates to include in the signed request. + +=item B<-nonce>, B<-no_nonce> + +Add an OCSP nonce extension to a request or disable OCSP nonce addition. +Normally if an OCSP request is input using the B<reqin> option no +nonce is added: using the B<nonce> option will force addition of a nonce. +If an OCSP request is being created (using B<cert> and B<serial> options) +a nonce is automatically added specifying B<no_nonce> overrides this. + +=item B<-req_text>, B<-resp_text>, B<-text> + +print out the text form of the OCSP request, response or both respectively. + +=item B<-reqout file>, B<-respout file> + +write out the DER encoded certificate request or response to B<file>. + +=item B<-reqin file>, B<-respin file> + +read OCSP request or response file from B<file>. These option are ignored +if OCSP request or response creation is implied by other options (for example +with B<serial>, B<cert> and B<host> options). + +=item B<-url responder_url> + +specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified. + +=item B<-host hostname:port>, B<-path pathname> + +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. This is equivalent to specifying B<-url> with scheme +http:// and the given hostname, port, and pathname. + +=item B<-header name=value> + +Adds the header B<name> with the specified B<value> to the OCSP request +that is sent to the responder. +This may be repeated. + +=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 +the signature on the OCSP response. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, +B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, +B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, +B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, +B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, +B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, +B<-verify_ip>, B<-verify_name>, B<-x509_strict> + +Set different certificate verification options. +See L<verify(1)> manual page for details. + +=item B<-verify_other file> + +file containing additional certificates to search when attempting to locate +the OCSP response signing certificate. Some responders omit the actual signer's +certificate from the response: this option can be used to supply the necessary +certificate in such cases. + +=item B<-trust_other> + +the certificates specified by the B<-verify_other> option should be explicitly +trusted and no additional checks will be performed on them. This is useful +when the complete responder certificate chain is not available or trusting a +root CA is not appropriate. + +=item B<-VAfile file> + +file containing explicitly trusted responder certificates. Equivalent to the +B<-verify_other> and B<-trust_other> options. + +=item B<-noverify> + +don't attempt to verify the OCSP response signature or the nonce values. This +option will normally only be used for debugging since it disables all verification +of the responders certificate. + +=item B<-no_intern> + +ignore certificates contained in the OCSP response when searching for the +signers certificate. With this option the signers certificate must be specified +with either the B<-verify_other> or B<-VAfile> options. + +=item B<-no_signature_verify> + +don't check the signature on the OCSP response. Since this option tolerates invalid +signatures on OCSP responses it will normally only be used for testing purposes. + +=item B<-no_cert_verify> + +don't verify the OCSP response signers certificate at all. Since this option allows +the OCSP response to be signed by any certificate it should only be used for +testing purposes. + +=item B<-no_chain> + +do not use certificates in the response as additional untrusted CA +certificates. + +=item B<-no_explicit> + +do not explicitly trust the root CA if it is set to be trusted for OCSP signing. + +=item B<-no_cert_checks> + +don't perform any additional checks on the OCSP response signers certificate. +That is do not make any checks to see if the signers certificate is authorised +to provide the necessary status information: as a result this option should +only be used for testing purposes. + +=item B<-validity_period nsec>, B<-status_age age> + +these options specify the range of times, in seconds, which will be tolerated +in an OCSP response. Each certificate status response includes a B<notBefore> +time and an optional B<notAfter> time. The current time should fall between +these two values, but the interval between the two times may be only a few +seconds. In practice the OCSP responder and clients clocks may not be precisely +synchronised and so such a check may fail. To avoid this the +B<-validity_period> option can be used to specify an acceptable error range in +seconds, the default value is 5 minutes. + +If the B<notAfter> time is omitted from a response then this means that new +status information is immediately available. In this case the age of the +B<notBefore> field is checked to see it is not older than B<age> seconds old. +By default this additional check is not performed. + +=item B<-[digest]> + +this option sets digest algorithm to use for certificate identification in the +OCSP request. Any digest supported by the OpenSSL B<dgst> command can be used. +The default is SHA-1. This option may be used multiple times to specify the +digest used by subsequent certificate identifiers. + +=back + +=head2 OCSP Server Options + +=over 4 + +=item B<-index indexfile> + +B<indexfile> is a text index file in B<ca> format containing certificate revocation +information. + +If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise +it is in client mode. The request(s) the responder processes can be either specified on +the command line (using B<issuer> and B<serial> options), supplied in a file (using the +B<reqin> option) or via external OCSP clients (if B<port> or B<url> is specified). + +If the B<index> option is present then the B<CA> and B<rsigner> options must also be +present. + +=item B<-CA file> + +CA certificate corresponding to the revocation information in B<indexfile>. + +=item B<-rsigner file> + +The certificate to sign OCSP responses with. + +=item B<-rother file> + +Additional certificates to include in the OCSP response. + +=item B<-resp_no_certs> + +Don't include any certificates in the OCSP response. + +=item B<-resp_key_id> + +Identify the signer certificate using the key ID, default is to use the subject name. + +=item B<-rkey file> + +The private key to sign OCSP responses with: if not present the file specified in the +B<rsigner> option is used. + +=item B<-port portnum> + +Port to listen for OCSP requests on. The port may also be specified using the B<url> +option. + +=item B<-nrequest number> + +The OCSP server will exit after receiving B<number> requests, default unlimited. + +=item B<-nmin minutes>, B<-ndays days> + +Number of minutes or days when fresh revocation information is available: used in the +B<nextUpdate> field. If neither option is present then the B<nextUpdate> field +is omitted meaning fresh revocation information is immediately available. + +=back + +=head1 OCSP Response verification. + +OCSP Response follows the rules specified in RFC2560. + +Initially the OCSP responder certificate is located and the signature on +the OCSP request checked using the responder certificate's public key. + +Then a normal certificate verify is performed on the OCSP responder certificate +building up a certificate chain in the process. The locations of the trusted +certificates used to build the chain can be specified by the B<CAfile> +and B<CApath> options or they will be looked for in the standard OpenSSL +certificates directory. + +If the initial verify fails then the OCSP verify process halts with an +error. + +Otherwise the issuing CA certificate in the request is compared to the OCSP +responder certificate: if there is a match then the OCSP verify succeeds. + +Otherwise the OCSP responder certificate's CA is checked against the issuing +CA certificate in the request. If there is a match and the OCSPSigning +extended key usage is present in the OCSP responder certificate then the +OCSP verify succeeds. + +Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders +CA is checked to see if it is trusted for OCSP signing. If it is the OCSP +verify succeeds. + +If none of these checks is successful then the OCSP verify fails. + +What this effectively means if that if the OCSP responder certificate is +authorised directly by the CA it is issuing revocation information about +(and it is correctly configured) then verification will succeed. + +If the OCSP responder is a "global responder" which can give details about +multiple CAs and has its own separate certificate chain then its root +CA can be trusted for OCSP signing. For example: + + openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem + +Alternatively the responder certificate itself can be explicitly trusted +with the B<-VAfile> option. + +=head1 NOTES + +As noted, most of the verify options are for testing or debugging purposes. +Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global +VA') B<-VAfile> options need to be used. + +The OCSP server is only useful for test and demonstration purposes: it is +not really usable as a full OCSP responder. It contains only a very +simple HTTP request handling and can only handle the POST form of OCSP +queries. It also handles requests serially meaning it cannot respond to +new requests until it has processed the current one. The text index file +format of revocation is also inefficient for large quantities of revocation +data. + +It is possible to run the B<ocsp> application in responder mode via a CGI +script using the B<reqin> and B<respout> options. + +=head1 EXAMPLES + +Create an OCSP request and write it to a file: + + openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der + +Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the +response to a file, print it out in text form, and verify the response: + + openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \ + -url http://ocsp.myhost.com/ -resp_text -respout resp.der + +Read in an OCSP response and print out text form: + + openssl ocsp -respin resp.der -text -noverify + +OCSP server on port 8888 using a standard B<ca> configuration, and a separate +responder certificate. All requests and responses are printed to a file. + + openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem + -text -out log.txt + +As above but exit after processing one request: + + openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem + -nrequest 1 + +Query status information using an internally generated request: + + openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem + -issuer demoCA/cacert.pem -serial 1 + +Query status information using request read from a file, and write the response +to a second file. + + openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem + -reqin req.der -respout resp.der + +=head1 HISTORY + +The -no_alt_chains options was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/openssl.pod b/openssl-1.1.0h/doc/apps/openssl.pod new file mode 100644 index 0000000..6e822a6 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/openssl.pod @@ -0,0 +1,461 @@ +=pod + +=head1 NAME + +openssl - OpenSSL command line tool + +=head1 SYNOPSIS + +B<openssl> +I<command> +[ I<command_opts> ] +[ I<command_args> ] + +B<openssl> B<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<public-key-algorithms>] + +B<openssl> B<no->I<XXX> [ I<arbitrary options> ] + +=head1 DESCRIPTION + +OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL +v2/v3) and Transport Layer Security (TLS v1) network protocols and related +cryptography standards required by them. + +The B<openssl> program is a command line tool for using the various +cryptography functions of OpenSSL's B<crypto> library from the shell. +It can be used for + + o Creation and management of private keys, public keys and parameters + o Public key cryptographic operations + o Creation of X.509 certificates, CSRs and CRLs + o Calculation of Message Digests + o Encryption and Decryption with Ciphers + o SSL/TLS Client and Server Tests + o Handling of S/MIME signed or encrypted mail + o Time Stamp requests, generation and verification + +=head1 COMMAND SUMMARY + +The B<openssl> program provides a rich variety of commands (I<command> in the +SYNOPSIS above), each of which often has a wealth of options and arguments +(I<command_opts> and I<command_args> in the SYNOPSIS). + +Many commands use an external configuration file for some or all of their +arguments and have a B<-config> option to specify that file. +The environment variable B<OPENSSL_CONF> can be used to specify +the location of the file. +If the environment variable is not specified, then the file is named +B<openssl.cnf> in the default certificate storage area, whose value +depends on the configuration flags specified when the OpenSSL +was built. + +The list parameters B<standard-commands>, B<digest-commands>, +and B<cipher-commands> output a list (one entry per line) of the names +of all standard commands, message digest commands, or cipher commands, +respectively, that are available in the present B<openssl> utility. + +The list parameters B<cipher-algorithms> and +B<digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as: + + from => to + +The list parameter B<public-key-algorithms> lists all supported public +key algorithms. + +The command B<no->I<XXX> tests whether a command of the +specified name is available. If no command named I<XXX> exists, it +returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1 +and prints I<XXX>. In both cases, the output goes to B<stdout> and +nothing is printed to B<stderr>. Additional command line arguments +are always ignored. Since for each cipher there is a command of the +same name, this provides an easy way for shell scripts to test for the +availability of ciphers in the B<openssl> program. (B<no->I<XXX> is +not able to detect pseudo-commands such as B<quit>, +B<list>, or B<no->I<XXX> itself.) + +=head2 Standard Commands + +=over 4 + +=item L<B<asn1parse>|asn1parse(1)> + +Parse an ASN.1 sequence. + +=item L<B<ca>|ca(1)> + +Certificate Authority (CA) Management. + +=item L<B<ciphers>|ciphers(1)> + +Cipher Suite Description Determination. + +=item L<B<cms>|cms(1)> + +CMS (Cryptographic Message Syntax) utility. + +=item L<B<crl>|crl(1)> + +Certificate Revocation List (CRL) Management. + +=item L<B<crl2pkcs7>|crl2pkcs7(1)> + +CRL to PKCS#7 Conversion. + +=item L<B<dgst>|dgst(1)> + +Message Digest Calculation. + +=item B<dh> + +Diffie-Hellman Parameter Management. +Obsoleted by L<B<dhparam>|dhparam(1)>. + +=item L<B<dhparam>|dhparam(1)> + +Generation and Management of Diffie-Hellman Parameters. Superseded by +L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>. + +=item L<B<dsa>|dsa(1)> + +DSA Data Management. + +=item L<B<dsaparam>|dsaparam(1)> + +DSA Parameter Generation and Management. Superseded by +L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>. + +=item L<B<ec>|ec(1)> + +EC (Elliptic curve) key processing. + +=item L<B<ecparam>|ecparam(1)> + +EC parameter manipulation and generation. + +=item L<B<enc>|enc(1)> + +Encoding with Ciphers. + +=item L<B<engine>|engine(1)> + +Engine (loadable module) information and manipulation. + +=item L<B<errstr>|errstr(1)> + +Error Number to Error String Conversion. + +=item B<gendh> + +Generation of Diffie-Hellman Parameters. +Obsoleted by L<B<dhparam>|dhparam(1)>. + +=item L<B<gendsa>|gendsa(1)> + +Generation of DSA Private Key from Parameters. Superseded by +L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>. + +=item L<B<genpkey>|genpkey(1)> + +Generation of Private Key or Parameters. + +=item L<B<genrsa>|genrsa(1)> + +Generation of RSA Private Key. Superseded by L<B<genpkey>|genpkey(1)>. + +=item L<B<nseq>|nseq(1)> + +Create or examine a Netscape certificate sequence. + +=item L<B<ocsp>|ocsp(1)> + +Online Certificate Status Protocol utility. + +=item L<B<passwd>|passwd(1)> + +Generation of hashed passwords. + +=item L<B<pkcs12>|pkcs12(1)> + +PKCS#12 Data Management. + +=item L<B<pkcs7>|pkcs7(1)> + +PKCS#7 Data Management. + +=item L<B<pkcs8>|pkcs8(1)> + +PKCS#8 format private key conversion tool. + +=item L<B<pkey>|pkey(1)> + +Public and private key management. + +=item L<B<pkeyparam>|pkeyparam(1)> + +Public key algorithm parameter management. + +=item L<B<pkeyutl>|pkeyutl(1)> + +Public key algorithm cryptographic operation utility. + +=item L<B<rand>|rand(1)> + +Generate pseudo-random bytes. + +=item L<B<rehash>|rehash(1)> + +Create symbolic links to certificate and CRL files named by the hash values. + +=item L<B<req>|req(1)> + +PKCS#10 X.509 Certificate Signing Request (CSR) Management. + +=item L<B<rsa>|rsa(1)> + +RSA key management. + + +=item L<B<rsautl>|rsautl(1)> + +RSA utility for signing, verification, encryption, and decryption. Superseded +by L<B<pkeyutl>|pkeyutl(1)>. + +=item L<B<s_client>|s_client(1)> + +This implements a generic SSL/TLS client which can establish a transparent +connection to a remote server speaking SSL/TLS. It's intended for testing +purposes only and provides only rudimentary interface functionality but +internally uses mostly all functionality of the OpenSSL B<ssl> library. + +=item L<B<s_server>|s_server(1)> + +This implements a generic SSL/TLS server which accepts connections from remote +clients speaking SSL/TLS. It's intended for testing purposes only and provides +only rudimentary interface functionality but internally uses mostly all +functionality of the OpenSSL B<ssl> library. It provides both an own command +line oriented protocol for testing SSL functions and a simple HTTP response +facility to emulate an SSL/TLS-aware webserver. + +=item L<B<s_time>|s_time(1)> + +SSL Connection Timer. + +=item L<B<sess_id>|sess_id(1)> + +SSL Session Data Management. + +=item L<B<smime>|smime(1)> + +S/MIME mail processing. + +=item L<B<speed>|speed(1)> + +Algorithm Speed Measurement. + +=item L<B<spkac>|spkac(1)> + +SPKAC printing and generating utility. + +=item L<B<ts>|ts(1)> + +Time Stamping Authority tool (client/server). + +=item L<B<verify>|verify(1)> + +X.509 Certificate Verification. + +=item L<B<version>|version(1)> + +OpenSSL Version Information. + +=item L<B<x509>|x509(1)> + +X.509 Certificate Data Management. + +=back + +=head2 Message Digest Commands + +=over 4 + +=item B<md2> + +MD2 Digest + +=item B<md5> + +MD5 Digest + +=item B<mdc2> + +MDC2 Digest + +=item B<rmd160> + +RMD-160 Digest + +=item B<sha> + +SHA Digest + +=item B<sha1> + +SHA-1 Digest + +=item B<sha224> + +SHA-224 Digest + +=item B<sha256> + +SHA-256 Digest + +=item B<sha384> + +SHA-384 Digest + +=item B<sha512> + +SHA-512 Digest + +=back + +=head2 Encoding and Cipher Commands + +=over 4 + +=item B<base64> + +Base64 Encoding + +=item B<bf bf-cbc bf-cfb bf-ecb bf-ofb> + +Blowfish Cipher + +=item B<cast cast-cbc> + +CAST Cipher + +=item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb> + +CAST5 Cipher + +=item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb> + +DES Cipher + +=item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb> + +Triple-DES Cipher + +=item B<idea idea-cbc idea-cfb idea-ecb idea-ofb> + +IDEA Cipher + +=item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb> + +RC2 Cipher + +=item B<rc4> + +RC4 Cipher + +=item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb> + +RC5 Cipher + +=back + +=head1 OPTIONS + +Details of which options are available depend on the specific command. +This section describes some common options with common behavior. + +=head2 Common Options + +=over 4 + +=item B<-help> + +Provides a terse summary of all options. + +=back + +=head2 Pass Phrase Options + +Several commands accept password arguments, typically using B<-passin> +and B<-passout> for input and output passwords respectively. These allow +the password to be obtained from a variety of sources. Both of these +options take a single argument whose format is described below. If no +password argument is given and a password is required then the user is +prompted to enter one: this will typically be read from the current +terminal with echoing turned off. + +=over 4 + +=item B<pass:password> + +The actual password is B<password>. Since the password is visible +to utilities (like 'ps' under Unix) this form should only be used +where security is not important. + +=item B<env:var> + +Obtain the password from the environment variable B<var>. Since +the environment of other processes is visible on certain platforms +(e.g. ps under certain Unix OSes) this option should be used with caution. + +=item B<file:pathname> + +The first line of B<pathname> is the password. If the same B<pathname> +argument is supplied to B<-passin> and B<-passout> arguments then the first +line will be used for the input password and the next line for the output +password. B<pathname> need not refer to a regular file: it could for example +refer to a device or named pipe. + +=item B<fd:number> + +Read the password from the file descriptor B<number>. This can be used to +send the data via a pipe for example. + +=item B<stdin> + +Read the password from standard input. + +=back + +=head1 SEE ALSO + +L<asn1parse(1)>, L<ca(1)>, L<ciphers(1)>, L<cms(1)>, L<config(5)>, +L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>, +L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>, +L<ec(1)>, L<ecparam(1)>, +L<enc(1)>, L<engine(1)>, L<errstr(1)>, L<gendsa(1)>, L<genpkey(1)>, +L<genrsa(1)>, L<nseq(1)>, L<ocsp(1)>, +L<passwd(1)>, +L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>, +L<pkey(1)>, L<pkeyparam(1)>, L<pkeyutl(1)>, +L<rand(1)>, L<rehash(1)>, L<req(1)>, L<rsa(1)>, +L<rsautl(1)>, L<s_client(1)>, +L<s_server(1)>, L<s_time(1)>, L<sess_id(1)>, +L<smime(1)>, L<speed(1)>, L<spkac(1)>, +L<ts(1)>, +L<verify(1)>, L<version(1)>, L<x509(1)>, +L<crypto(7)>, L<ssl(7)>, L<x509v3_config(5)> + +=head1 HISTORY + +The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0; +For notes on the availability of other commands, see their individual +manual pages. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/passwd.pod b/openssl-1.1.0h/doc/apps/passwd.pod new file mode 100644 index 0000000..4663201 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/passwd.pod @@ -0,0 +1,97 @@ +=pod + +=head1 NAME + +openssl-passwd, +passwd - compute password hashes + +=head1 SYNOPSIS + +B<openssl passwd> +[B<-help>] +[B<-crypt>] +[B<-1>] +[B<-apr1>] +[B<-salt> I<string>] +[B<-in> I<file>] +[B<-stdin>] +[B<-noverify>] +[B<-quiet>] +[B<-table>] +{I<password>} + +=head1 DESCRIPTION + +The B<passwd> command computes the hash of a password typed at +run-time or the hash of each password in a list. The password list is +taken from the named file for option B<-in file>, from stdin for +option B<-stdin>, or from the command line, or from the terminal otherwise. +The Unix standard algorithm B<crypt> and the MD5-based BSD password +algorithm B<1> and its Apache variant B<apr1> are available. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-crypt> + +Use the B<crypt> algorithm (default). + +=item B<-1> + +Use the MD5 based BSD password algorithm B<1>. + +=item B<-apr1> + +Use the B<apr1> algorithm (Apache variant of the BSD algorithm). + +=item B<-salt> I<string> + +Use the specified salt. +When reading a password from the terminal, this implies B<-noverify>. + +=item B<-in> I<file> + +Read passwords from I<file>. + +=item B<-stdin> + +Read passwords from B<stdin>. + +=item B<-noverify> + +Don't verify when reading a password from the terminal. + +=item B<-quiet> + +Don't output warnings when passwords given at the command line are truncated. + +=item B<-table> + +In the output list, prepend the cleartext password and a TAB character +to each password hash. + +=back + +=head1 EXAMPLES + +B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>. + +B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.>. + +B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/pkcs12.pod b/openssl-1.1.0h/doc/apps/pkcs12.pod new file mode 100644 index 0000000..44ee3d4 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/pkcs12.pod @@ -0,0 +1,381 @@ +=pod + +=head1 NAME + +openssl-pkcs12, +pkcs12 - PKCS#12 file utility + +=head1 SYNOPSIS + +B<openssl> B<pkcs12> +[B<-help>] +[B<-export>] +[B<-chain>] +[B<-inkey file_or_id>] +[B<-certfile filename>] +[B<-name name>] +[B<-caname name>] +[B<-in filename>] +[B<-out filename>] +[B<-noout>] +[B<-nomacver>] +[B<-nocerts>] +[B<-clcerts>] +[B<-cacerts>] +[B<-nokeys>] +[B<-info>] +[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>] +[B<-noiter>] +[B<-maciter | -nomaciter | -nomac>] +[B<-twopass>] +[B<-descert>] +[B<-certpbe cipher>] +[B<-keypbe cipher>] +[B<-macalg digest>] +[B<-keyex>] +[B<-keysig>] +[B<-password arg>] +[B<-passin arg>] +[B<-passout arg>] +[B<-rand file(s)>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-CSP name>] + +=head1 DESCRIPTION + +The B<pkcs12> command allows PKCS#12 files (sometimes referred to as +PFX files) to be created and parsed. PKCS#12 files are used by several +programs including Netscape, MSIE and MS Outlook. + +=head1 OPTIONS + +There are a lot of options the meaning of some depends of whether a PKCS#12 file +is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 +file can be created by using the B<-export> option (see below). + +=head1 PARSING OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies filename of the PKCS#12 file to be parsed. Standard input is used +by default. + +=item B<-out filename> + +The filename to write certificates and private keys to, standard output by +default. They are all written in PEM format. + +=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 +L<openssl(1)>. + +=item B<-passout arg> + +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)>. + +=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 +version of the PKCS#12 file. + +=item B<-clcerts> + +only output client certificates (not CA certificates). + +=item B<-cacerts> + +only output CA certificates (not client certificates). + +=item B<-nocerts> + +no certificates at all will be output. + +=item B<-nokeys> + +no private keys will be output. + +=item B<-info> + +output additional information about the PKCS#12 file structure, algorithms used and +iteration counts. + +=item B<-des> + +use DES to encrypt private keys before outputting. + +=item B<-des3> + +use triple DES to encrypt private keys before outputting, this is the default. + +=item B<-idea> + +use IDEA to encrypt private keys before outputting. + +=item B<-aes128>, B<-aes192>, B<-aes256> + +use AES to encrypt private keys before outputting. + +=item B<-camellia128>, B<-camellia192>, B<-camellia256> + +use Camellia to encrypt private keys before outputting. + +=item B<-nodes> + +don't encrypt the private keys at all. + +=item B<-nomacver> + +don't attempt to verify the integrity MAC before reading the file. + +=item B<-twopass> + +prompt for separate integrity and encryption passwords: most software +always assumes these are the same so this option will render such +PKCS#12 files unreadable. + +=back + +=head1 FILE CREATION OPTIONS + +=over 4 + +=item B<-export> + +This option specifies that a PKCS#12 file will be created rather than +parsed. + +=item B<-out filename> + +This specifies filename to write the PKCS#12 file to. Standard output is used +by default. + +=item B<-in filename> + +The filename to read certificates and private keys from, standard input by +default. They must all be in PEM format. The order doesn't matter but one +private key and its corresponding certificate should be present. If additional +certificates are present they will also be included in the PKCS#12 file. + +=item B<-inkey file_or_id> + +file to read private key from. If not present then a private key must be present +in the input file. +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. + +=item B<-name friendlyname> + +This specifies the "friendly name" for the certificate and private key. This +name is typically displayed in list boxes by software importing the file. + +=item B<-certfile filename> + +A filename to read additional certificates from. + +=item B<-caname friendlyname> + +This specifies the "friendly name" for other certificates. This option may be +used multiple times to specify names for all certificates in the order they +appear. Netscape ignores friendly names on other certificates whereas MSIE +displays them. + +=item B<-pass arg>, B<-passout arg> + +the PKCS#12 file (i.e. output file) password source. For more information about +the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in +L<openssl(1)>. + +=item B<-passin password> + +pass phrase source to decrypt any input private keys with. For more information +about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in +L<openssl(1)>. + +=item B<-chain> + +if this option is present then an attempt is made to include the entire +certificate chain of the user certificate. The standard CA store is used +for this search. If the search fails it is considered a fatal error. + +=item B<-descert> + +encrypt the certificate using triple DES, this may render the PKCS#12 +file unreadable by some "export grade" software. By default the private +key is encrypted using triple DES and the certificate using 40 bit RC2. + +=item B<-keypbe alg>, B<-certpbe alg> + +these options allow the algorithm used to encrypt the private key and +certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name +can be used (see B<NOTES> section for more information). If a cipher name +(as output by the B<list-cipher-algorithms> command is specified then it +is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only +use PKCS#12 algorithms. + +=item B<-keyex|-keysig> + +specifies that the private key is to be used for key exchange or just signing. +This option is only interpreted by MSIE and similar MS software. Normally +"export grade" software will only allow 512 bit RSA keys to be used for +encryption purposes but arbitrary length keys for signing. The B<-keysig> +option marks the key for signing only. Signing only keys can be used for +S/MIME signing, authenticode (ActiveX control signing) and SSL client +authentication, however due to a bug only MSIE 5.0 and later support +the use of signing only keys for SSL client authentication. + +=item B<-macalg digest> + +specify the MAC digest algorithm. If not included them SHA1 will be used. + +=item B<-nomaciter>, B<-noiter> + +these options affect the iteration counts on the MAC and key algorithms. +Unless you wish to produce files compatible with MSIE 4.0 you should leave +these options alone. + +To discourage attacks by using large dictionaries of common passwords the +algorithm that derives keys from passwords can have an iteration count applied +to it: this causes a certain part of the algorithm to be repeated and slows it +down. The MAC is used to check the file integrity but since it will normally +have the same password as the keys and certificates it could also be attacked. +By default both MAC and encryption iteration counts are set to 2048, using +these options the MAC and encryption iteration counts can be set to 1, since +this reduces the file security you should not use these options unless you +really have to. Most software supports both MAC and key iteration counts. +MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> +option. + +=item B<-maciter> + +This option is included for compatibility with previous versions, it used +to be needed to use MAC iterations counts but they are now used by default. + +=item B<-nomac> + +don't attempt to provide the MAC integrity. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-CAfile file> + +CA storage as a file. + +=item B<-CApath dir> + +CA storage as a directory. This directory must be a standard certificate +directory: that is a hash of each subject name (using B<x509 -hash>) should be +linked to each certificate. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-CSP name> + +write B<name> as a Microsoft CSP name. + +=back + +=head1 NOTES + +Although there are a large number of options most of them are very rarely +used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used +for PKCS#12 file creation B<-export> and B<-name> are also used. + +If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present +then all certificates will be output in the order they appear in the input +PKCS#12 files. There is no guarantee that the first certificate present is +the one corresponding to the private key. Certain software which requires +a private key and certificate and assumes the first certificate in the +file is the one corresponding to the private key: this may not always +be the case. Using the B<-clcerts> option will solve this problem by only +outputting the certificate corresponding to the private key. If the CA +certificates are required then they can be output to a separate file using +the B<-nokeys -cacerts> options to just output CA certificates. + +The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption +algorithms for private keys and certificates to be specified. Normally +the defaults are fine but occasionally software can't handle triple DES +encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can +be used to reduce the private key encryption to 40 bit RC2. A complete +description of all algorithms is contained in the B<pkcs8> manual page. + +Prior 1.1 release passwords containing non-ASCII characters were encoded +in non-compliant manner, which limited interoperability, in first hand +with Windows. But switching to standard-compliant password encoding +poses problem accessing old data protected with broken encoding. For +this reason even legacy encodings is attempted when reading the +data. If you use PKCS#12 files in production application you are advised +to convert the data, because implemented heuristic approach is not +MT-safe, its sole goal is to facilitate the data upgrade with this +utility. + +=head1 EXAMPLES + +Parse a PKCS#12 file and output it to a file: + + openssl pkcs12 -in file.p12 -out file.pem + +Output only client certificates to a file: + + openssl pkcs12 -in file.p12 -clcerts -out file.pem + +Don't encrypt the private key: + + openssl pkcs12 -in file.p12 -out file.pem -nodes + +Print some info about a PKCS#12 file: + + openssl pkcs12 -in file.p12 -info -noout + +Create a PKCS#12 file: + + openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" + +Include some extra certificates: + + openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \ + -certfile othercerts.pem + +=head1 SEE ALSO + +L<pkcs8(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/pkcs7.pod b/openssl-1.1.0h/doc/apps/pkcs7.pod new file mode 100644 index 0000000..340b72d --- /dev/null +++ b/openssl-1.1.0h/doc/apps/pkcs7.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + +openssl-pkcs7, +pkcs7 - PKCS#7 utility + +=head1 SYNOPSIS + +B<openssl> B<pkcs7> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-out filename>] +[B<-print_certs>] +[B<-text>] +[B<-noout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<pkcs7> command processes PKCS#7 files in DER or PEM format. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. B<DER> format is DER encoded PKCS#7 +v1.5 structure.B<PEM> (the default) is a base64 encoded version of +the DER form with header and footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read from or standard input if this +option is not specified. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-print_certs> + +prints out any certificates or CRLs contained in the file. They are +preceded by their subject and issuer names in one line format. + +=item B<-text> + +prints out certificates details in full rather than just subject and +issuer names. + +=item B<-noout> + +don't output the encoded version of the PKCS#7 structure (or certificates +is B<-print_certs> is set). + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<pkcs7> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 EXAMPLES + +Convert a PKCS#7 file from PEM to DER: + + openssl pkcs7 -in file.pem -outform DER -out file.der + +Output all certificates in a file: + + openssl pkcs7 -in file.pem -print_certs -out certs.pem + +=head1 NOTES + +The PEM PKCS#7 format uses the header and footer lines: + + -----BEGIN PKCS7----- + -----END PKCS7----- + +For compatibility with some CAs it will also accept: + + -----BEGIN CERTIFICATE----- + -----END CERTIFICATE----- + +=head1 RESTRICTIONS + +There is no option to print out all the fields of a PKCS#7 file. + +This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they +cannot currently parse, for example, the new CMS as described in RFC2630. + +=head1 SEE ALSO + +L<crl2pkcs7(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/pkcs8.pod b/openssl-1.1.0h/doc/apps/pkcs8.pod new file mode 100644 index 0000000..402e7b2 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/pkcs8.pod @@ -0,0 +1,302 @@ +=pod + +=head1 NAME + +openssl-pkcs8, +pkcs8 - PKCS#8 format private key conversion tool + +=head1 SYNOPSIS + +B<openssl> B<pkcs8> +[B<-help>] +[B<-topk8>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-iter count>] +[B<-noiter>] +[B<-nocrypt>] +[B<-traditional>] +[B<-v2 alg>] +[B<-v2prf alg>] +[B<-v1 alg>] +[B<-engine id>] +[B<-scrypt>] +[B<-scrypt_N N>] +[B<-scrypt_r r>] +[B<-scrypt_p p>] + +=head1 DESCRIPTION + +The B<pkcs8> command processes private keys in PKCS#8 format. It can handle +both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo +format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-topk8> + +Normally a PKCS#8 private key is expected on input and a private key will be +written to the output file. With the B<-topk8> option the situation is +reversed: it reads a private key and writes a PKCS#8 format key. + +=item B<-inform DER|PEM> + +This specifies the input format: see L<KEY FORMATS> for more details. + +=item B<-outform DER|PEM> + +This specifies the output format: see L<KEY FORMATS> for more details. + +=item B<-traditional> + +When this option is present and B<-topk8> is not a traditional format private +key is written. + +=item B<-in filename> + +This specifies the input filename to read a key from or standard input if this +option is not specified. If the key is encrypted a pass phrase will be +prompted for. + +=item B<-passin arg> + +the input file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output by +default. If any encryption options are set then a pass phrase will be +prompted for. The output filename should B<not> be the same as the input +filename. + +=item B<-passout arg> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-iter count> + +When creating new PKCS#8 containers, use a given number of iterations on +the password in deriving the encryption key for the PKCS#8 output. +High values increase the time required to brute-force a PKCS#8 container. + +=item B<-nocrypt> + +PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo +structures using an appropriate password based encryption algorithm. With +this option an unencrypted PrivateKeyInfo structure is expected or output. +This option does not encrypt private keys at all and should only be used +when absolutely necessary. Certain software such as some versions of Java +code signing software used unencrypted private keys. + +=item B<-v2 alg> + +This option sets the PKCS#5 v2.0 algorithm. + +The B<alg> argument is the encryption algorithm to use, valid values include +B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256> +is used. + +=item B<-v2prf alg> + +This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value +value would be B<hmacWithSHA256>. If this option isn't set then the default +for the cipher is used or B<hmacWithSHA256> if there is no default. + +Some implementations may not support custom PRF algorithms and may require +the B<hmacWithSHA1> option to work. + +=item B<-v1 alg> + +This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some +older implementations may not support PKCS#5 v2.0 and may require this option. +If not specified PKCS#5 v2.0 form is used. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<pkcs8> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-scrypt> + +uses the B<scrypt> algorithm for private key encryption using default +parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit +key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>, +B<-scrypt_p> and B<-v2> options. + +B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p> + +sets the scrypt B<N>, B<r> or B<p> parameters. + +=back + +=head1 KEY FORMATS + +Various different formats are used by the pkcs8 utility. These are detailed +below. + +If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is +not used) then the input file must be in PKCS#8 format. An encrypted +key is expected unless B<-nocrypt> is included. + +If B<-topk8> is not used and B<PEM> mode is set the output file will be an +unencrypted private key in PKCS#8 format. If the B<-traditional> option is +used then a traditional format private key is written instead. + +If B<-topk8> is not used and B<DER> mode is set the output file will be an +unencrypted private key in traditional DER format. + +If B<-topk8> is used then any supported private key can be used for the input +file in a format specified by B<-inform>. The output file will be encrypted +PKCS#8 format using the specified encryption parameters unless B<-nocrypt> +is included. + +=head1 NOTES + +By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit +AES with HMAC and SHA256 is used. + +Some older implementations do not support PKCS#5 v2.0 format and require +the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak +encryption algorithms such as 56 bit DES. + +The encrypted form of a PEM encode PKCS#8 files uses the following +headers and footers: + + -----BEGIN ENCRYPTED PRIVATE KEY----- + -----END ENCRYPTED PRIVATE KEY----- + +The unencrypted form uses: + + -----BEGIN PRIVATE KEY----- + -----END PRIVATE KEY----- + +Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration +counts are more secure that those encrypted using the traditional +SSLeay compatible formats. So if additional security is considered +important the keys should be converted. + +It is possible to write out DER encoded encrypted private keys in +PKCS#8 format because the encryption details are included at an ASN1 +level whereas the traditional format includes them at a PEM level. + +=head1 PKCS#5 v1.5 and PKCS#12 algorithms. + +Various algorithms can be used with the B<-v1> command line option, +including PKCS#5 v1.5 and PKCS#12. These are described in more detail +below. + +=over 4 + +=item B<PBE-MD2-DES PBE-MD5-DES> + +These algorithms were included in the original PKCS#5 v1.5 specification. +They only offer 56 bits of protection since they both use DES. + +=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES> + +These algorithms are not mentioned in the original PKCS#5 v1.5 specification +but they use the same key derivation algorithm and are supported by some +software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or +56 bit DES. + +=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40> + +These algorithms use the PKCS#12 password based encryption algorithm and +allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. + +=back + +=head1 EXAMPLES + +Convert a private key to PKCS#8 format using default parameters (AES with +256 bit key and B<hmacWithSHA256>): + + openssl pkcs8 -in key.pem -topk8 -out enckey.pem + +Convert a private key to PKCS#8 unencrypted format: + + openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem + +Convert a private key to PKCS#5 v2.0 format using triple DES: + + openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem + +Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC +mode and B<hmacWithSHA512> PRF: + + openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem + +Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm +(DES): + + openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem + +Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm +(3DES): + + openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES + +Read a DER unencrypted PKCS#8 format private key: + + openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem + +Convert a private key from any PKCS#8 encrypted format to traditional format: + + openssl pkcs8 -in pk8.pem -traditional -out key.pem + +Convert a private key to PKCS#8 format, encrypting with AES-256 and with +one million iterations of the password: + + openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem + +=head1 STANDARDS + +Test vectors from this PKCS#5 v2.0 implementation were posted to the +pkcs-tng mailing list using triple DES, DES and RC2 with high iteration +counts, several people confirmed that they could decrypt the private +keys produced and Therefore it can be assumed that the PKCS#5 v2.0 +implementation is reasonably accurate at least as far as these +algorithms are concerned. + +The format of PKCS#8 DSA (and other) private keys is not well documented: +it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA +PKCS#8 private key format complies with this standard. + +=head1 BUGS + +There should be an option that prints out the encryption algorithm +in use and other details such as the iteration count. + +=head1 SEE ALSO + +L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>, +L<gendsa(1)> + +=head1 HISTORY + +The B<-iter> option was added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/pkey.pod b/openssl-1.1.0h/doc/apps/pkey.pod new file mode 100644 index 0000000..ef2e463 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/pkey.pod @@ -0,0 +1,156 @@ +=pod + +=head1 NAME + +openssl-pkey, +pkey - public or private key processing tool + +=head1 SYNOPSIS + +B<openssl> B<pkey> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-traditional>] +[B<-cipher>] +[B<-text>] +[B<-text_pub>] +[B<-noout>] +[B<-pubin>] +[B<-pubout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<pkey> command processes public or private keys. They can be converted +between various forms and their components printed out. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format DER or PEM. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read a key from or standard input if this +option is not specified. If the key is encrypted a pass phrase will be +prompted for. + +=item B<-passin arg> + +the input file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output if this +option is not specified. If any encryption options are set then a pass phrase +will be prompted for. The output filename should B<not> be the same as the input +filename. + +=item B<-passout password> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-traditional> + +normally a private key is written using standard format: this is PKCS#8 form +with the appropriate encryption algorithm (if any). If the B<-traditional> +option is specified then the older "traditional" format is used instead. + +=item B<-cipher> + +These options encrypt the private key with the supplied cipher. Any algorithm +name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>. + +=item B<-text> + +prints out the various public or private key components in +plain text in addition to the encoded version. + +=item B<-text_pub> + +print out only public key components even if a private key is being processed. + +=item B<-noout> + +do not output the encoded version of the key. + +=item B<-pubin> + +by default a private key is read from the input file: with this +option a public key is read instead. + +=item B<-pubout> + +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<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<pkey> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 EXAMPLES + +To remove the pass phrase on an RSA private key: + + openssl pkey -in key.pem -out keyout.pem + +To encrypt a private key using triple DES: + + openssl pkey -in key.pem -des3 -out keyout.pem + +To convert a private key from PEM to DER format: + + openssl pkey -in key.pem -outform DER -out keyout.der + +To print out the components of a private key to standard output: + + openssl pkey -in key.pem -text -noout + +To print out the public components of a private key to standard output: + + openssl pkey -in key.pem -text_pub -noout + +To just output the public part of a private key: + + openssl pkey -in key.pem -pubout -out pubkey.pem + +=head1 SEE ALSO + +L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>, +L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)> + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/pkeyparam.pod b/openssl-1.1.0h/doc/apps/pkeyparam.pod new file mode 100644 index 0000000..309e249 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/pkeyparam.pod @@ -0,0 +1,83 @@ +=pod + +=head1 NAME + +openssl-pkeyparam, +pkeyparam - public key algorithm parameter processing tool + +=head1 SYNOPSIS + +B<openssl> B<pkeyparam> +[B<-help>] +[B<-in filename>] +[B<-out filename>] +[B<-text>] +[B<-noout>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<pkey> command processes public or private keys. They can be converted +between various forms and their components printed out. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read parameters from or standard input if +this option is not specified. + +=item B<-out filename> + +This specifies the output filename to write parameters to or standard output if +this option is not specified. + +=item B<-text> + +prints out the parameters in plain text in addition to the encoded version. + +=item B<-noout> + +do not output the encoded version of the parameters. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<pkeyparam> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 EXAMPLE + +Print out text version of parameters: + + openssl pkeyparam -in param.pem -text + +=head1 NOTES + +There are no B<-inform> or B<-outform> options for this command because only +PEM format is supported because the key type is determined by the PEM headers. + +=head1 SEE ALSO + +L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>, +L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)> + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/pkeyutl.pod b/openssl-1.1.0h/doc/apps/pkeyutl.pod new file mode 100644 index 0000000..e72486d --- /dev/null +++ b/openssl-1.1.0h/doc/apps/pkeyutl.pod @@ -0,0 +1,293 @@ +=pod + +=head1 NAME + +openssl-pkeyutl, +pkeyutl - public key algorithm utility + +=head1 SYNOPSIS + +B<openssl> B<pkeyutl> +[B<-help>] +[B<-in file>] +[B<-out file>] +[B<-sigfile file>] +[B<-inkey file>] +[B<-keyform PEM|DER|ENGINE>] +[B<-passin arg>] +[B<-peerkey file>] +[B<-peerform PEM|DER|ENGINE>] +[B<-pubin>] +[B<-certin>] +[B<-rev>] +[B<-sign>] +[B<-verify>] +[B<-verifyrecover>] +[B<-encrypt>] +[B<-decrypt>] +[B<-derive>] +[B<-kdf algorithm>] +[B<-kdflen length>] +[B<-pkeyopt opt:value>] +[B<-hexdump>] +[B<-asn1parse>] +[B<-engine id>] +[B<-engine_impl>] + +=head1 DESCRIPTION + +The B<pkeyutl> command can be used to perform public key operations using +any supported algorithm. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read data from or standard input +if this option is not specified. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-sigfile file> + +Signature file, required for B<verify> operations only + +=item B<-inkey file> + +the input key file, by default it should be a private key. + +=item B<-keyform PEM|DER|ENGINE> + +the key format PEM, DER or ENGINE. Default is PEM. + +=item B<-passin arg> + +the input key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + + +=item B<-peerkey file> + +the peer key file, used by key derivation (agreement) operations. + +=item B<-peerform PEM|DER|ENGINE> + +the peer key format PEM, DER or ENGINE. Default is PEM. + +=item B<-pubin> + +the input file is a public key. + +=item B<-certin> + +the input is a certificate containing a public key. + +=item B<-rev> + +reverse the order of the input buffer. This is useful for some libraries +(such as CryptoAPI) which represent the buffer in little endian format. + +=item B<-sign> + +sign the input data and output the signed result. This requires +a private key. + +=item B<-verify> + +verify the input data against the signature file and indicate if the +verification succeeded or failed. + +=item B<-verifyrecover> + +verify the input data and output the recovered data. + +=item B<-encrypt> + +encrypt the input data using a public key. + +=item B<-decrypt> + +decrypt the input data using a private key. + +=item B<-derive> + +derive a shared secret using the peer key. + +=item B<-kdf algorithm> + +Use key derivation function B<algorithm>. The supported algorithms are +at present B<TLS1-PRF> and B<HKDF>. +Note: additional parameters and the KDF output length will normally have to be +set for this to work. +See L<EVP_PKEY_CTX_set_hkdf_md(3)> and L<EVP_PKEY_CTX_set_tls1_prf_md(3)> +for the supported string parameters of each algorithm. + +=item B<-kdflen length> + +Set the output length for KDF. + +=item B<-pkeyopt opt:value> + +Public key options specified as opt:value. See NOTES below for more details. + +=item B<-hexdump> + +hex dump the output data. + +=item B<-asn1parse> + +asn1parse the output data, this is useful when combined with the +B<-verifyrecover> option when an ASN1 structure is signed. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<pkeyutl> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-engine_impl> + +When used with the B<-engine> option, it specifies to also use +engine B<id> for crypto operations. + +=back + +=head1 NOTES + +The operations and options supported vary according to the key algorithm +and its implementation. The OpenSSL operations and options are indicated below. + +Unless otherwise mentioned all algorithms support the B<digest:alg> option +which specifies the digest in use for sign, verify and verifyrecover operations. +The value B<alg> should represent a digest name as used in the +EVP_get_digestbyname() function for example B<sha1>. +This value is used only for sanity-checking the lengths of data passed in to +the B<pkeyutl> and for creating the structures that make up the signature +(e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures). +In case of RSA, ECDSA and DSA signatures, this utility +will not perform hashing on input data but rather use the data directly as +input of signature algorithm. Depending on key type, signature type and mode +of padding, the maximum acceptable lengths of input data differ. In general, +with RSA the signed data can't be longer than the key modulus, in case of ECDSA +and DSA the data shouldn't be longer than field size, otherwise it will be +silently truncated to field size. + +In other words, if the value of digest is B<sha1> the input should be 20 bytes +long binary encoding of SHA-1 hash function output. + +=head1 RSA ALGORITHM + +The RSA algorithm generally supports the encrypt, decrypt, sign, +verify and verifyrecover operations. However, some padding modes +support only a subset of these operations. The following additional +B<pkeyopt> values are supported: + +=over 4 + +=item B<rsa_padding_mode:mode> + +This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for +PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep> +for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS. + +In PKCS#1 padding if the message digest is not set then the supplied data is +signed or verified directly instead of using a B<DigestInfo> structure. If a +digest is set then the a B<DigestInfo> structure is used and its the length +must correspond to the digest type. + +For B<oaep> mode only encryption and decryption is supported. + +For B<x931> if the digest type is set it is used to format the block data +otherwise the first byte is used to specify the X9.31 digest ID. Sign, +verify and verifyrecover are can be performed in this mode. + +For B<pss> mode only sign and verify are supported and the digest type must be +specified. + +=item B<rsa_pss_saltlen:len> + +For B<pss> mode only this option specifies the salt length. Two special values +are supported: -1 sets the salt length to the digest length. When signing -2 +sets the salt length to the maximum permissible value. When verifying -2 causes +the salt length to be automatically determined based on the B<PSS> block +structure. + +=back + +=head1 DSA ALGORITHM + +The DSA algorithm supports signing and verification operations only. Currently +there are no additional options other than B<digest>. Only the SHA1 +digest can be used and this digest is assumed by default. + +=head1 DH ALGORITHM + +The DH algorithm only supports the derivation operation and no additional +options. + +=head1 EC ALGORITHM + +The EC algorithm supports sign, verify and derive operations. The sign and +verify operations use ECDSA and derive uses ECDH. Currently there are no +additional options other than B<digest>. Only the SHA1 digest can be used and +this digest is assumed by default. + +=head1 X25519 ALGORITHM + +The X25519 algorithm supports key derivation only. Currently there are no +additional options. + +=head1 EXAMPLES + +Sign some data using a private key: + + openssl pkeyutl -sign -in file -inkey key.pem -out sig + +Recover the signed data (e.g. if an RSA key is used): + + openssl pkeyutl -verifyrecover -in sig -inkey key.pem + +Verify the signature (e.g. a DSA key): + + openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem + +Sign data using a message digest value (this is currently only valid for RSA): + + openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256 + +Derive a shared secret value: + + openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret + +Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and +seed consisting of the single byte 0xFF: + + openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \ + -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump + +=head1 SEE ALSO + +L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)> +L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>, +L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)> + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/rand.pod b/openssl-1.1.0h/doc/apps/rand.pod new file mode 100644 index 0000000..4cdb370 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/rand.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +openssl-rand, +rand - generate pseudo-random bytes + +=head1 SYNOPSIS + +B<openssl rand> +[B<-help>] +[B<-out> I<file>] +[B<-rand> I<file(s)>] +[B<-base64>] +[B<-hex>] +I<num> + +=head1 DESCRIPTION + +The B<rand> command outputs I<num> pseudo-random bytes after seeding +the random number generator once. As in other B<openssl> command +line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd> +in addition to the files given in the B<-rand> option. A new +I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough +seeding was obtained from these sources. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-out> I<file> + +Write to I<file> instead of standard output. + +=item B<-rand> I<file(s)> + +Use specified file or files or EGD socket (see L<RAND_egd(3)>) +for seeding the random number generator. +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-base64> + +Perform base64 encoding on the output. + +=item B<-hex> + +Show the output as a hex string. + +=back + +=head1 SEE ALSO + +L<RAND_bytes(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/rehash.pod b/openssl-1.1.0h/doc/apps/rehash.pod new file mode 100644 index 0000000..79268d4 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/rehash.pod @@ -0,0 +1,140 @@ +=pod + +=for comment +Original text by James Westby, contributed under the OpenSSL license. + +=head1 NAME + +openssl-c_rehash, openssl-rehash, +c_rehash, rehash - Create symbolic links to files named by the hash values + +=head1 SYNOPSIS + +B<openssl> +B<rehash> +B<[-h]> +B<[-help]> +B<[-old]> +B<[-n]> +B<[-v]> +[ I<directory>...] + +B<c_rehash> +I<flags...> + +=head1 DESCRIPTION + +On some platforms, the OpenSSL B<rehash> command is available as +an external script called B<c_rehash>. They are functionally equivalent, +except for minor differences noted below. + +B<rehash> scans directories and calculates a hash value of each +C<.pem>, C<.crt>, C<.cer>, or C<.crl> +file in the specified directory list and creates symbolic links +for each file, where the name of the link is the hash value. +(If the platform does not support symbolic links, a copy is made.) +This 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 should 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 an error will be generated. + +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<rehash> will first remove all links +that have a name in that syntax, even if they are being used for some +other purpose. +To skip the removal step, use the B<-n> flag. +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 files that +cannot be parsed as either a certificate or a CRL or if +more than one such object appears in the file. + +=head2 Script Configuration + +The B<c_rehash> script +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 FILENAME + $OPENSSL crl -hash -fingerprint -noout -in FILENAME + +where B<FILENAME> is the filename. It must output the hash of the +file on the first line, and the fingerprint on the second, +optionally prefixed with some text and an equals sign. + +=head1 OPTIONS + +=over 4 + +=item B<-help> B<-h> + +Display a brief usage message. + +=item B<-old> + +Use old-style hashing (MD5, as opposed to SHA-1) for generating +links to be used for releases before 1.0.0. +Note that current versions will not use the old style. + +=item B<-n> + +Do not remove existing links. +This is needed when keeping new and old-style links in the same directory. + +=item B<-v> + +Print messages about old links removed and new links created. +By default, B<rehash> only lists each directory as it is processed. + +=back + +=head1 ENVIRONMENT + +=over 4 + +=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)>, +L<crl(1)>. +L<x509(1)>. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/req.pod b/openssl-1.1.0h/doc/apps/req.pod new file mode 100644 index 0000000..c5b5260 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/req.pod @@ -0,0 +1,662 @@ +=pod + +=head1 NAME + +openssl-req, +req - PKCS#10 certificate request and certificate generating utility + +=head1 SYNOPSIS + +B<openssl> B<req> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER>] +[B<-in filename>] +[B<-passin arg>] +[B<-out filename>] +[B<-passout arg>] +[B<-text>] +[B<-pubkey>] +[B<-noout>] +[B<-verify>] +[B<-modulus>] +[B<-new>] +[B<-rand file(s)>] +[B<-newkey rsa:bits>] +[B<-newkey alg:file>] +[B<-nodes>] +[B<-key filename>] +[B<-keyform PEM|DER>] +[B<-keyout filename>] +[B<-keygen_engine id>] +[B<-[digest]>] +[B<-config filename>] +[B<-multivalue-rdn>] +[B<-x509>] +[B<-days n>] +[B<-set_serial n>] +[B<-newhdr>] +[B<-extensions section>] +[B<-reqexts section>] +[B<-utf8>] +[B<-nameopt>] +[B<-reqopt>] +[B<-subject>] +[B<-subj arg>] +[B<-batch>] +[B<-verbose>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<req> command primarily creates and processes certificate requests +in PKCS#10 format. It can additionally create self signed certificates +for use as root CAs for example. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option uses an ASN1 DER encoded +form compatible with the PKCS#10. The B<PEM> form is the default format: it +consists of the B<DER> format base64 encoded with additional header and +footer lines. + +=item B<-outform DER|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read a request from or standard input +if this option is not specified. A request is only read if the creation +options (B<-new> and B<-newkey>) are not specified. + +=item B<-passin arg> + +the input file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-out filename> + +This specifies the output filename to write to or standard output by +default. + +=item B<-passout arg> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-text> + +prints out the certificate request in text form. + +=item B<-subject> + +prints out the request subject (or certificate subject if B<-x509> is +specified) + +=item B<-pubkey> + +outputs the public key. + +=item B<-noout> + +this option prevents output of the encoded version of the request. + +=item B<-modulus> + +this option prints out the value of the modulus of the public key +contained in the request. + +=item B<-verify> + +verifies the signature on the request. + +=item B<-new> + +this option generates a new certificate request. It will prompt +the user for the relevant field values. The actual fields +prompted for and their maximum and minimum sizes are specified +in the configuration file and any requested extensions. + +If the B<-key> option is not used it will generate a new RSA private +key using information specified in the configuration file. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-newkey arg> + +this option creates a new certificate request and a new private +key. The argument takes one of several forms. B<rsa:nbits>, where +B<nbits> is the number of bits, generates an RSA key B<nbits> +in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified, +the default key size, specified in the configuration file is used. + +All other algorithms support the B<-newkey alg:file> form, where file may be +an algorithm parameter file, created by the B<genpkey -genparam> command +or and X.509 certificate for a key with appropriate algorithm. + +B<param:file> generates a key using the parameter file or certificate B<file>, +the algorithm is determined by the parameters. B<algname:file> use algorithm +B<algname> and parameter file B<file>: the two algorithms must match or an +error occurs. B<algname> just uses algorithm B<algname>, and parameters, +if necessary should be specified via B<-pkeyopt> parameter. + +B<dsa:filename> generates a DSA key using the parameters +in the file B<filename>. B<ec:filename> generates EC key (usable both with +ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R +34.10-2001 key (requires B<ccgost> engine configured in the configuration +file). If just B<gost2001> is specified a parameter set should be +specified by B<-pkeyopt paramset:X> + + +=item B<-pkeyopt opt:value> + +set the public key algorithm option B<opt> to B<value>. The precise set of +options supported depends on the public key algorithm used and its +implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page +for more details. + +=item B<-key filename> + +This specifies the file to read the private key from. It also +accepts PKCS#8 format private keys for PEM format files. + +=item B<-keyform PEM|DER> + +the format of the private key file specified in the B<-key> +argument. PEM is the default. + +=item B<-keyout filename> + +this gives the filename to write the newly created private key to. +If this option is not specified then the filename present in the +configuration file is used. + +=item B<-nodes> + +if this option is specified then if a private key is created it +will not be encrypted. + +=item B<-[digest]> + +this specifies the message digest to sign the request. +Any digest supported by the OpenSSL B<dgst> command can be used. +This overrides the digest algorithm specified in +the configuration file. + +Some public key algorithms may override this choice. For instance, DSA +signatures always use SHA1, GOST R 34.10 signatures always use +GOST R 34.11-94 (B<-md_gost94>). + +=item B<-config filename> + +this allows an alternative configuration file to be specified. +Optional; for a description of the default value, +see L<openssl(1)/COMMAND SUMMARY>. + +=item B<-subj arg> + +sets subject name for new request or supersedes the subject name +when processing a request. +The arg must be formatted as I</type0=value0/type1=value1/type2=...>, +characters may be escaped by \ (backslash), no spaces are skipped. + +=item B<-multivalue-rdn> + +this option causes the -subj argument to be interpreted with full +support for multivalued RDNs. Example: + +I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> + +If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>. + +=item B<-x509> + +this option outputs a self signed certificate instead of a certificate +request. This is typically used to generate a test certificate or +a self signed root CA. The extensions added to the certificate +(if any) are specified in the configuration file. Unless specified +using the B<set_serial> option, a large random number will be used for +the serial number. + +If existing request is specified with the B<-in> option, it is converted +to the self signed certificate otherwise new request is created. + +=item B<-days n> + +when the B<-x509> option is being used this specifies the number of +days to certify the certificate for. The default is 30 days. + +=item B<-set_serial n> + +serial number to use when outputting a self signed certificate. This +may be specified as a decimal value or a hex value if preceded by B<0x>. + +=item B<-extensions section> + +=item B<-reqexts section> + +these options specify alternative sections to include certificate +extensions (if the B<-x509> option is present) or certificate +request extensions. This allows several different sections to +be used in the same configuration file to specify requests for +a variety of purposes. + +=item B<-utf8> + +this option causes field values to be interpreted as UTF8 strings, by +default they are interpreted as ASCII. This means that the field +values, whether prompted from a terminal or obtained from a +configuration file, must be valid UTF8 strings. + +=item B<-nameopt option> + +option which determines how the subject or issuer names are displayed. The +B<option> argument can be a single option or multiple options separated by +commas. Alternatively the B<-nameopt> switch may be used more than once to +set multiple options. See the L<x509(1)> manual page for details. + +=item B<-reqopt> + +customise the output format used with B<-text>. The B<option> argument can be +a single option or multiple options separated by commas. + +See discussion of the B<-certopt> parameter in the L<x509(1)> +command. + +=item B<-newhdr> + +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> + +non-interactive mode. + +=item B<-verbose> + +print extra details about the operations being performed. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<req> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-keygen_engine id> + +specifies an engine (by its unique B<id> string) which would be used +for key generation operations. + +=back + +=head1 CONFIGURATION FILE FORMAT + +The configuration options are specified in the B<req> section of +the configuration file. As with all configuration files if no +value is specified in the specific section (i.e. B<req>) then +the initial unnamed or B<default> section is searched too. + +The options available are described in detail below. + +=over 4 + +=item B<input_password output_password> + +The passwords for the input private key file (if present) and +the output private key file (if one will be created). The +command line options B<passin> and B<passout> override the +configuration file values. + +=item B<default_bits> + +Specifies the default key size in bits. + +This option is used in conjunction with the B<-new> option to generate +a new key. It can be overridden by specifying an explicit key size in +the B<-newkey> option. The smallest accepted key size is 512 bits. If +no key size is specified then 2048 bits is used. + +=item B<default_keyfile> + +This is the default filename to write a private key to. If not +specified the key is written to standard output. This can be +overridden by the B<-keyout> option. + +=item B<oid_file> + +This specifies a file containing additional B<OBJECT IDENTIFIERS>. +Each line of the file should consist of the numerical form of the +object identifier followed by white space then the short name followed +by white space and finally the long name. + +=item B<oid_section> + +This specifies a section in the configuration file containing extra +object identifiers. Each line should consist of the short name of the +object identifier followed by B<=> and the numerical form. The short +and long names are the same when this option is used. + +=item B<RANDFILE> + +This specifies a filename in which random number seed information is +placed and read from, or an EGD socket (see L<RAND_egd(3)>). +It is used for private key generation. + +=item B<encrypt_key> + +If this is set to B<no> then if a private key is generated it is +B<not> encrypted. This is equivalent to the B<-nodes> command line +option. For compatibility B<encrypt_rsa_key> is an equivalent option. + +=item B<default_md> + +This option specifies the digest algorithm to use. +Any digest supported by the OpenSSL B<dgst> command can be used. +If not present then MD5 is used. +This option can be overridden on the command line. + +=item B<string_mask> + +This option masks out the use of certain string types in certain +fields. Most users will not need to change this option. + +It can be set to several values B<default> which is also the default +option uses PrintableStrings, T61Strings and BMPStrings if the +B<pkix> value is used then only PrintableStrings and BMPStrings will +be used. This follows the PKIX recommendation in RFC2459. If the +B<utf8only> option is used then only UTF8Strings will be used: this +is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr> +option just uses PrintableStrings and T61Strings: certain software has +problems with BMPStrings and UTF8Strings: in particular Netscape. + +=item B<req_extensions> + +this specifies the configuration file section containing a list of +extensions to add to the certificate request. It can be overridden +by the B<-reqexts> command line switch. See the +L<x509v3_config(5)> manual page for details of the +extension section format. + +=item B<x509_extensions> + +this specifies the configuration file section containing a list of +extensions to add to certificate generated when the B<-x509> switch +is used. It can be overridden by the B<-extensions> command line switch. + +=item B<prompt> + +if set to the value B<no> this disables prompting of certificate fields +and just takes values from the config file directly. It also changes the +expected format of the B<distinguished_name> and B<attributes> sections. + +=item B<utf8> + +if set to the value B<yes> then field values to be interpreted as UTF8 +strings, by default they are interpreted as ASCII. This means that +the field values, whether prompted from a terminal or obtained from a +configuration file, must be valid UTF8 strings. + +=item B<attributes> + +this specifies the section containing any request attributes: its format +is the same as B<distinguished_name>. Typically these may contain the +challengePassword or unstructuredName types. They are currently ignored +by OpenSSL's request signing utilities but some CAs might want them. + +=item B<distinguished_name> + +This specifies the section containing the distinguished name fields to +prompt for when generating a certificate or certificate request. The format +is described in the next section. + +=back + +=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT + +There are two separate formats for the distinguished name and attribute +sections. If the B<prompt> option is set to B<no> then these sections +just consist of field names and values: for example, + + CN=My Name + OU=My Organization + emailAddress=someone@somewhere.org + +This allows external programs (e.g. GUI based) to generate a template file +with all the field names and values and just pass it to B<req>. An example +of this kind of configuration file is contained in the B<EXAMPLES> section. + +Alternatively if the B<prompt> option is absent or not set to B<no> then the +file contains field prompting information. It consists of lines of the form: + + fieldName="prompt" + fieldName_default="default field value" + fieldName_min= 2 + fieldName_max= 4 + +"fieldName" is the field name being used, for example commonName (or CN). +The "prompt" string is used to ask the user to enter the relevant +details. If the user enters nothing then the default value is used if no +default value is present then the field is omitted. A field can +still be omitted if a default value is present if the user just +enters the '.' character. + +The number of characters entered must be between the fieldName_min and +fieldName_max limits: there may be additional restrictions based +on the field being used (for example countryName can only ever be +two characters long and must fit in a PrintableString). + +Some fields (such as organizationName) can be used more than once +in a DN. This presents a problem because configuration files will +not recognize the same name occurring twice. To avoid this problem +if the fieldName contains some characters followed by a full stop +they will be ignored. So for example a second organizationName can +be input by calling it "1.organizationName". + +The actual permitted field names are any object identifier short or +long names. These are compiled into OpenSSL and include the usual +values such as commonName, countryName, localityName, organizationName, +organizationalUnitName, stateOrProvinceName. Additionally emailAddress +is include as well as name, surname, givenName initials and dnQualifier. + +Additional object identifiers can be defined with the B<oid_file> or +B<oid_section> options in the configuration file. Any additional fields +will be treated as though they were a DirectoryString. + + +=head1 EXAMPLES + +Examine and verify certificate request: + + openssl req -in req.pem -text -verify -noout + +Create a private key and then generate a certificate request from it: + + openssl genrsa -out key.pem 2048 + openssl req -new -key key.pem -out req.pem + +The same but just using req: + + openssl req -newkey rsa:2048 -keyout key.pem -out req.pem + +Generate a self signed root certificate: + + openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem + +Example of a file pointed to by the B<oid_file> option: + + 1.2.3.4 shortName A longer Name + 1.2.3.6 otherName Other longer Name + +Example of a section pointed to by B<oid_section> making use of variable +expansion: + + testoid1=1.2.3.5 + testoid2=${testoid1}.6 + +Sample configuration file prompting for field values: + + [ req ] + default_bits = 2048 + default_keyfile = privkey.pem + distinguished_name = req_distinguished_name + attributes = req_attributes + req_extensions = v3_ca + + dirstring_type = nobmp + + [ req_distinguished_name ] + countryName = Country Name (2 letter code) + countryName_default = AU + countryName_min = 2 + countryName_max = 2 + + localityName = Locality Name (eg, city) + + organizationalUnitName = Organizational Unit Name (eg, section) + + commonName = Common Name (eg, YOUR name) + commonName_max = 64 + + emailAddress = Email Address + emailAddress_max = 40 + + [ req_attributes ] + challengePassword = A challenge password + challengePassword_min = 4 + challengePassword_max = 20 + + [ v3_ca ] + + subjectKeyIdentifier=hash + authorityKeyIdentifier=keyid:always,issuer:always + basicConstraints = critical, CA:true + +Sample configuration containing all field values: + + + RANDFILE = $ENV::HOME/.rnd + + [ req ] + default_bits = 2048 + default_keyfile = keyfile.pem + distinguished_name = req_distinguished_name + attributes = req_attributes + prompt = no + output_password = mypass + + [ req_distinguished_name ] + C = GB + ST = Test State or Province + L = Test Locality + O = Organization Name + OU = Organizational Unit Name + CN = Common Name + emailAddress = test@email.address + + [ req_attributes ] + challengePassword = A challenge password + + +=head1 NOTES + +The header and footer lines in the B<PEM> format are normally: + + -----BEGIN CERTIFICATE REQUEST----- + -----END CERTIFICATE REQUEST----- + +some software (some versions of Netscape certificate server) instead needs: + + -----BEGIN NEW CERTIFICATE REQUEST----- + -----END NEW CERTIFICATE REQUEST----- + +which is produced with the B<-newhdr> option but is otherwise compatible. +Either form is accepted transparently on input. + +The certificate requests generated by B<Xenroll> with MSIE have extensions +added. It includes the B<keyUsage> extension which determines the type of +key (signature only or general purpose) and any additional OIDs entered +by the script in an extendedKeyUsage extension. + +=head1 DIAGNOSTICS + +The following messages are frequently asked about: + + Using configuration from /some/path/openssl.cnf + Unable to load config info + +This is followed some time later by... + + unable to find 'distinguished_name' in config + problems making Certificate Request + +The first error message is the clue: it can't find the configuration +file! Certain operations (like examining a certificate request) don't +need a configuration file so its use isn't enforced. Generation of +certificates or requests however does need a configuration file. This +could be regarded as a bug. + +Another puzzling message is this: + + Attributes: + a0:00 + +this is displayed when no attributes are present and the request includes +the correct empty B<SET OF> structure (the DER encoding of which is 0xa0 +0x00). If you just see: + + Attributes: + +then the B<SET OF> is missing and the encoding is technically invalid (but +it is tolerated). See the description of the command line option B<-asn1-kludge> +for more information. + +=head1 BUGS + +OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively +treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. +This can cause problems if you need characters that aren't available in +PrintableStrings and you don't want to or can't use BMPStrings. + +As a consequence of the T61String handling the only correct way to represent +accented characters in OpenSSL is to use a BMPString: unfortunately Netscape +currently chokes on these. If you have to use accented characters with Netscape +and MSIE then you currently need to use the invalid T61String form. + +The current prompting is not very friendly. It doesn't allow you to confirm what +you've just entered. Other things like extensions in certificate requests are +statically defined in the configuration file. Some of these: like an email +address in subjectAltName should be input by the user. + +=head1 SEE ALSO + +L<x509(1)>, L<ca(1)>, L<genrsa(1)>, +L<gendsa(1)>, L<config(5)>, +L<x509v3_config(5)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/rsa.pod b/openssl-1.1.0h/doc/apps/rsa.pod new file mode 100644 index 0000000..dcbf514 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/rsa.pod @@ -0,0 +1,217 @@ +=pod + +=head1 NAME + +openssl-rsa, +rsa - RSA key processing tool + +=head1 SYNOPSIS + +B<openssl> B<rsa> +[B<-help>] +[B<-inform PEM|NET|DER>] +[B<-outform PEM|NET|DER>] +[B<-in filename>] +[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>] +[B<-text>] +[B<-noout>] +[B<-modulus>] +[B<-check>] +[B<-pubin>] +[B<-pubout>] +[B<-RSAPublicKey_in>] +[B<-RSAPublicKey_out>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<rsa> command processes RSA keys. They can be converted between various +forms and their components printed out. B<Note> this command uses the +traditional SSLeay compatible format for private key encryption: newer +applications should use the more secure PKCS#8 format using the B<pkcs8> +utility. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|NET|PEM> + +This specifies the input format. The B<DER> option uses an ASN1 DER encoded +form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format. +The B<PEM> form is the default format: it consists of the B<DER> format base64 +encoded with additional header and footer lines. On input PKCS#8 format private +keys are also accepted. The B<NET> form is a format is described in the B<NOTES> +section. + +=item B<-outform DER|NET|PEM> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read a key from or standard input if this +option is not specified. If the key is encrypted a pass phrase will be +prompted for. + +=item B<-passin arg> + +the input file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-out filename> + +This specifies the output filename to write a key to or standard output if this +option is not specified. If any encryption options are set then a pass phrase +will be prompted for. The output filename should B<not> be the same as the input +filename. + +=item B<-passout password> + +the output file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea> + +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 +setting the encryption options it can be use to add or change the pass phrase. +These options can only be used with PEM format output files. + +=item B<-text> + +prints out the various public or private key components in +plain text in addition to the encoded version. + +=item B<-noout> + +this option prevents output of the encoded version of the key. + +=item B<-modulus> + +this option prints out the value of the modulus of the key. + +=item B<-check> + +this option checks the consistency of an RSA private key. + +=item B<-pubin> + +by default a private key is read from the input file: with this +option a public key is read instead. + +=item B<-pubout> + +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> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 NOTES + +The PEM private key format uses the header and footer lines: + + -----BEGIN RSA PRIVATE KEY----- + -----END RSA PRIVATE KEY----- + +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. + +Some newer version of IIS have additional data in the exported .key +files. To use these with the utility, view the file with a binary editor +and look for the string "private-key", then trace back to the byte +sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data +from this point onwards to another file and use that as the input +to the B<rsa> utility with the B<-inform NET> option. + +=head1 EXAMPLES + +To remove the pass phrase on an RSA private key: + + openssl rsa -in key.pem -out keyout.pem + +To encrypt a private key using triple DES: + + openssl rsa -in key.pem -des3 -out keyout.pem + +To convert a private key from PEM to DER format: + + openssl rsa -in key.pem -outform DER -out keyout.der + +To print out the components of a private key to standard output: + + openssl rsa -in key.pem -text -noout + +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 +B<NET> format. + +There should be an option that automatically handles .key files, +without having to manually edit them. + +=head1 SEE ALSO + +L<pkcs8(1)>, L<dsa(1)>, L<genrsa(1)>, +L<gendsa(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/rsautl.pod b/openssl-1.1.0h/doc/apps/rsautl.pod new file mode 100644 index 0000000..c07d60a --- /dev/null +++ b/openssl-1.1.0h/doc/apps/rsautl.pod @@ -0,0 +1,205 @@ +=pod + +=head1 NAME + +openssl-rsautl, +rsautl - RSA utility + +=head1 SYNOPSIS + +B<openssl> B<rsautl> +[B<-help>] +[B<-in file>] +[B<-out file>] +[B<-inkey file>] +[B<-keyform PEM|DER|ENGINE>] +[B<-pubin>] +[B<-certin>] +[B<-sign>] +[B<-verify>] +[B<-encrypt>] +[B<-decrypt>] +[B<-pkcs>] +[B<-ssl>] +[B<-raw>] +[B<-hexdump>] +[B<-asn1parse>] + +=head1 DESCRIPTION + +The B<rsautl> command can be used to sign, verify, encrypt and decrypt +data using the RSA algorithm. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read data from or standard input +if this option is not specified. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-inkey file> + +the input key file, by default it should be an RSA private key. + +=item B<-keyform PEM|DER|ENGINE> + +the key format PEM, DER or ENGINE. + +=item B<-pubin> + +the input file is an RSA public key. + +=item B<-certin> + +the input is a certificate containing an RSA public key. + +=item B<-sign> + +sign the input data and output the signed result. This requires +an RSA private key. + +=item B<-verify> + +verify the input data and output the recovered data. + +=item B<-encrypt> + +encrypt the input data using an RSA public key. + +=item B<-decrypt> + +decrypt the input data using an RSA private key. + +=item B<-pkcs, -oaep, -ssl, -raw> + +the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP, +special padding used in SSL v2 backwards compatible handshakes, +or no padding, respectively. +For signatures, only B<-pkcs> and B<-raw> can be used. + +=item B<-hexdump> + +hex dump the output data. + +=item B<-asn1parse> + +asn1parse the output data, this is useful when combined with the +B<-verify> option. + +=back + +=head1 NOTES + +B<rsautl> because it uses the RSA algorithm directly can only be +used to sign or verify small pieces of data. + +=head1 EXAMPLES + +Sign some data using a private key: + + openssl rsautl -sign -in file -inkey key.pem -out sig + +Recover the signed data + + openssl rsautl -verify -in sig -inkey key.pem + +Examine the raw signed data: + + openssl rsautl -verify -in sig -inkey key.pem -raw -hexdump + + 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ + 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world + +The PKCS#1 block formatting is evident from this. If this was done using +encrypt and decrypt the block would have been of type 2 (the second byte) +and random padding data visible instead of the 0xff bytes. + +It is possible to analyse the signature of certificates using this +utility in conjunction with B<asn1parse>. Consider the self signed +example in certs/pca-cert.pem . Running B<asn1parse> as follows yields: + + openssl asn1parse -in pca-cert.pem + + 0:d=0 hl=4 l= 742 cons: SEQUENCE + 4:d=1 hl=4 l= 591 cons: SEQUENCE + 8:d=2 hl=2 l= 3 cons: cont [ 0 ] + 10:d=3 hl=2 l= 1 prim: INTEGER :02 + 13:d=2 hl=2 l= 1 prim: INTEGER :00 + 16:d=2 hl=2 l= 13 cons: SEQUENCE + 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption + 29:d=3 hl=2 l= 0 prim: NULL + 31:d=2 hl=2 l= 92 cons: SEQUENCE + 33:d=3 hl=2 l= 11 cons: SET + 35:d=4 hl=2 l= 9 cons: SEQUENCE + 37:d=5 hl=2 l= 3 prim: OBJECT :countryName + 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU + .... + 599:d=1 hl=2 l= 13 cons: SEQUENCE + 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption + 612:d=2 hl=2 l= 0 prim: NULL + 614:d=1 hl=3 l= 129 prim: BIT STRING + + +The final BIT STRING contains the actual signature. It can be extracted with: + + openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614 + +The certificate public key can be extracted with: + + openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem + +The signature can be analysed with: + + openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin + + 0:d=0 hl=2 l= 32 cons: SEQUENCE + 2:d=1 hl=2 l= 12 cons: SEQUENCE + 4:d=2 hl=2 l= 8 prim: OBJECT :md5 + 14:d=2 hl=2 l= 0 prim: NULL + 16:d=1 hl=2 l= 16 prim: OCTET STRING + 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%.. + +This is the parsed version of an ASN1 DigestInfo structure. It can be seen that +the digest used was md5. The actual part of the certificate that was signed can +be extracted with: + + openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4 + +and its digest computed with: + + openssl md5 -c tbs + MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5 + +which it can be seen agrees with the recovered value above. + +=head1 SEE ALSO + +L<dgst(1)>, L<rsa(1)>, L<genrsa(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/s_client.pod b/openssl-1.1.0h/doc/apps/s_client.pod new file mode 100644 index 0000000..01a6c5f --- /dev/null +++ b/openssl-1.1.0h/doc/apps/s_client.pod @@ -0,0 +1,619 @@ +=pod + +=head1 NAME + +openssl-s_client, +s_client - SSL/TLS client program + +=head1 SYNOPSIS + +B<openssl> B<s_client> +[B<-help>] +[B<-connect host:port>] +[B<-proxy host:port>] +[B<-unix path>] +[B<-4>] +[B<-6>] +[B<-servername name>] +[B<-verify depth>] +[B<-verify_return_error>] +[B<-cert filename>] +[B<-certform DER|PEM>] +[B<-key filename>] +[B<-keyform DER|PEM>] +[B<-pass arg>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-dane_tlsa_domain domain>] +[B<-dane_tlsa_rrdata rrdata>] +[B<-dane_ee_no_namechecks>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-no_check_time>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level num>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-reconnect>] +[B<-showcerts>] +[B<-debug>] +[B<-msg>] +[B<-nbio_test>] +[B<-state>] +[B<-nbio>] +[B<-crlf>] +[B<-ign_eof>] +[B<-no_ign_eof>] +[B<-quiet>] +[B<-ssl3>] +[B<-tls1>] +[B<-tls1_1>] +[B<-tls1_2>] +[B<-no_ssl3>] +[B<-no_tls1>] +[B<-no_tls1_1>] +[B<-no_tls1_2>] +[B<-dtls>] +[B<-dtls1>] +[B<-dtls1_2>] +[B<-fallback_scsv>] +[B<-async>] +[B<-split_send_frag>] +[B<-max_pipelines>] +[B<-read_buf>] +[B<-bugs>] +[B<-comp>] +[B<-no_comp>] +[B<-sigalgs sigalglist>] +[B<-curves curvelist>] +[B<-cipher cipherlist>] +[B<-serverpref>] +[B<-starttls protocol>] +[B<-xmpphost hostname>] +[B<-engine id>] +[B<-tlsextdebug>] +[B<-no_ticket>] +[B<-sess_out filename>] +[B<-sess_in filename>] +[B<-rand file(s)>] +[B<-serverinfo types>] +[B<-status>] +[B<-alpn protocols>] +[B<-nextprotoneg protocols>] +[B<-ct|noct>] +[B<-ctlogfile>] + +=head1 DESCRIPTION + +The B<s_client> command implements a generic SSL/TLS client which connects +to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for +SSL servers. + +=head1 OPTIONS + +In addition to the options below the B<s_client> utility also supports the +common and client only options documented in the +in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)> +manual page. + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-connect host:port> + +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<-proxy host:port> + +When used with the B<-connect> flag, the program uses the host and port +specified with this flag and issues an HTTP CONNECT command to connect +to the desired server. + +=item B<-unix path> + +Connect over the specified Unix-domain socket. + +=item B<-4> + +Use IPv4 only. + +=item B<-6> + +Use IPv6 only. + +=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 +not to use a certificate. + +=item B<-certform format> + +The certificate format to use: DER or PEM. PEM is the default. + +=item B<-key keyfile> + +The private key to use. If not specified then the certificate file will +be used. + +=item B<-keyform format> + +The private format to use: DER or PEM. PEM is the default. + +=item B<-pass arg> + +the private key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-verify depth> + +The verify depth to use. This specifies the maximum length of the +server certificate chain and turns on server certificate verification. +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 +must be in "hash format", see B<verify> for more information. These are +also used when building the client certificate chain. + +=item B<-CAfile file> + +A file containing trusted certificates to use during server authentication +and to use when attempting to build the client certificate chain. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-dane_tlsa_domain domain> + +Enable RFC6698/RFC7671 DANE TLSA authentication and specify the +TLSA base domain which becomes the default SNI hint and the primary +reference identifier for hostname checks. This must be used in +combination with at least one instance of the B<-dane_tlsa_rrdata> +option below. + +When DANE authentication succeeds, the diagnostic output will include +the lowest (closest to 0) depth at which a TLSA record authenticated +a chain certificate. When that TLSA record is a "2 1 0" trust +anchor public key that signed (rather than matched) the top-most +certificate of the chain, the result is reported as "TA public key +verified". Otherwise, either the TLSA record "matched TA certificate" +at a positive depth or else "matched EE certificate" at depth 0. + +=item B<-dane_tlsa_rrdata rrdata> + +Use one or more times to specify the RRDATA fields of the DANE TLSA +RRset associated with the target service. The B<rrdata> value is +specied in "presentation form", that is four whitespace separated +fields that specify the usage, selector, matching type and associated +data, with the last of these encoded in hexadecimal. Optional +whitespace is ignored in the associated data field. For example: + + $ openssl s_client -brief -starttls smtp \ + -connect smtp.example.com:25 \ + -dane_tlsa_domain smtp.example.com \ + -dane_tlsa_rrdata "2 1 1 + B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \ + -dane_tlsa_rrdata "2 1 1 + 60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18" + ... + Verification: OK + Verified peername: smtp.example.com + DANE TLSA 2 1 1 ...ee12d2cc90180517616e8a18 matched TA certificate at depth 1 + ... + +=item B<-dane_ee_no_namechecks> + +This disables server name checks when authenticating via DANE-EE(3) TLSA +records. +For some applications, primarily web browsers, it is not safe to disable name +checks due to "unknown key share" attacks, in which a malicious server can +convince a client that a connection to a victim server is instead a secure +connection to the malicious server. +The malicious server may then be able to violate cross-origin scripting +restrictions. +Thus, despite the text of RFC7671, name checks are by default enabled for +DANE-EE(3) TLSA records, and can be disabled in applications where it is safe +to do so. +In particular, SMTP and XMPP clients should set this option as SRV and MX +records already make it possible for a remote domain to redirect client +connections to any server of its choice, and in any case SMTP and XMPP clients +do not execute scripts downloaded from remote servers. + +=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, +B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, +B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, +B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, +B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, +B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, +B<-verify_ip>, B<-verify_name>, B<-x509_strict> + +Set various certificate chain validation options. See the +L<verify(1)> manual page for details. + +=item B<-reconnect> + +reconnects to the same server 5 times using the same session ID, this can +be used as a test that session caching is working. + +=item B<-showcerts> + +display the whole server certificate chain: normally only the server +certificate itself is displayed. + +=item B<-prexit> + +print session information when the program exits. This will always attempt +to print out information even if the connection fails. Normally information +will only be printed out once if the connection succeeds. This option is useful +because the cipher in use may be renegotiated or the connection may fail +because a client certificate is required or is requested only after an +attempt is made to access a certain URL. Note: the output produced by this +option is not always accurate because a connection might never have been +established. + +=item B<-state> + +prints out the SSL session states. + +=item B<-debug> + +print extensive debugging information including a hex dump of all traffic. + +=item B<-msg> + +show all protocol messages with hex dump. + +=item B<-trace> + +show verbose trace output of protocol messages. OpenSSL needs to be compiled +with B<enable-ssl-trace> for this option to work. + +=item B<-msgfile> + +file to send output of B<-msg> or B<-trace> to, default standard output. + +=item B<-nbio_test> + +tests non-blocking I/O + +=item B<-nbio> + +turns on non-blocking I/O + +=item B<-crlf> + +this option translated a line feed from the terminal into CR+LF as required +by some servers. + +=item B<-ign_eof> + +inhibit shutting down the connection when end of file is reached in the +input. + +=item B<-quiet> + +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. +The default value is "Client_identity" (without the quotes). + +=item B<-psk key> + +Use the PSK key B<key> when using a PSK cipher suite. The key is +given as a hexadecimal number without leading 0x, for example -psk +1a2b3c4d. +This option must be provided in order to use a PSK cipher. + +=item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> + +These options require or disable the use of the specified SSL or TLS protocols. +By default B<s_client> will negotiate the highest mutually supported protocol +version. +When a specific TLS version is required, only that version will be offered to +and accepted from the server. + +=item B<-dtls>, B<-dtls1>, B<-dtls1_2> + +These options make B<s_client> use DTLS protocols instead of TLS. +With B<-dtls>, B<s_client> will negotiate any supported DTLS protocol version, +whilst B<-dtls1> and B<-dtls1_2> will only support DTLS1.0 and DTLS1.2 +respectively. + +=item B<-fallback_scsv> + +Send TLS_FALLBACK_SCSV in the ClientHello. + +=item B<-async> + +switch on asynchronous mode. Cryptographic operations will be performed +asynchronously. This will only have an effect if an asynchronous capable engine +is also used via the B<-engine> option. For test purposes the dummy async engine +(dasync) can be used (if available). + +=item B<-split_send_frag int> + +The size used to split data for encrypt pipelines. If more data is written in +one go than this value then it will be split into multiple pipelines, up to the +maximum number of pipelines defined by max_pipelines. This only has an effect if +a suitable ciphersuite has been negotiated, an engine that supports pipelining +has been loaded, and max_pipelines is greater than 1. See +L<SSL_CTX_set_split_send_fragment(3)> for further information. + +=item B<-max_pipelines int> + +The maximum number of encrypt/decrypt pipelines to be used. This will only have +an effect if an engine has been loaded that supports pipelining (e.g. the dasync +engine) and a suitable ciphersuite has been negotiated. The default value is 1. +See L<SSL_CTX_set_max_pipelines(3)> for further information. + +=item B<-read_buf int> + +The default read buffer size to be used for connections. This will only have an +effect if the buffer size is larger than the size that would otherwise be used +and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for +further information). + +=item B<-bugs> + +there are several known bug in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-comp> + +Enables support for SSL/TLS compression. +This option was introduced in OpenSSL 1.1.0. +TLS compression is not recommended and is off by default as of +OpenSSL 1.1.0. + +=item B<-no_comp> + +Disables support for SSL/TLS compression. +TLS compression is not recommended and is off by default as of +OpenSSL 1.1.0. + +=item B<-brief> + +only provide a brief summary of connection parameters instead of the +normal verbose output. + +=item B<-sigalgs sigalglist> + +Specifies the list of signature algorithms that are sent by the client. +The server selects one entry in the list based on its preferences. +For example strings, see L<SSL_CTX_set1_sigalgs(3)> + +=item B<-curves curvelist> + +Specifies the list of supported curves to be sent by the client. The curve is +is ultimately selected by the server. For a list of all curves, use: + + $ openssl ecparam -list_curves + +=item B<-cipher cipherlist> + +this allows the cipher list sent by the client to be modified. Although +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<-starttls protocol> + +send the protocol-specific message(s) to switch to TLS for communication. +B<protocol> is a keyword for the intended protocol. Currently, the only +supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server", +and "irc." + +=item B<-xmpphost hostname> + +This option, when used with "-starttls xmpp" or "-starttls xmpp-server", +specifies the host for the "to" attribute of the stream element. +If this option is not specified, then the host specified with "-connect" +will be used. + +=item B<-tlsextdebug> + +print out a hex dump of any TLS extensions received from the server. + +=item B<-no_ticket> + +disable RFC4507bis session ticket support. + +=item B<-sess_out filename> + +output SSL session to B<filename> + +=item B<-sess_in sess.pem> + +load SSL session from B<filename>. The client will attempt to resume a +connection from this session. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<s_client> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-serverinfo types> + +a list of comma-separated TLS Extension Types (numbers between 0 and +65535). Each type will be sent as an empty ClientHello TLS Extension. +The server's response (if any) will be encoded and displayed as a PEM +file. + +=item B<-status> + +sends a certificate status request to the server (OCSP stapling). The server +response (if any) is printed out. + +=item B<-alpn protocols>, B<-nextprotoneg protocols> + +these flags enable the +Enable the Application-Layer Protocol Negotiation or Next Protocol +Negotiation extension, respectively. ALPN is the IETF standard and +replaces NPN. +The B<protocols> list is a +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 +receiving ServerHello with a list of server supported protocols. + +=item B<-ct|noct> + +Use one of these two options to control whether Certificate Transparency (CT) +is enabled (B<-ct>) or disabled (B<-noct>). +If CT is enabled, signed certificate timestamps (SCTs) will be requested from +the server and reported at handshake completion. + +Enabling CT also enables OCSP stapling, as this is one possible delivery method +for SCTs. + +=item B<-ctlogfile> + +A file containing a list of known Certificate Transparency logs. See +L<SSL_CTX_set_ctlog_list_file(3)> for the expected file format. + +=back + +=head1 CONNECTED COMMANDS + +If a connection is established with an SSL server then any data received +from the server is displayed and any key presses will be sent to the +server. When used interactively (which means neither B<-quiet> nor B<-ign_eof> +have been given), the session will be renegotiated if the line begins with an +B<R>, and if the line begins with a B<Q> or if end of file is reached, the +connection will be closed down. + +=head1 NOTES + +B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP +server the command: + + openssl s_client -connect servername:443 + +would typically be used (https uses port 443). If the connection succeeds +then an HTTP command can be given such as "GET /" to retrieve a web page. + +If the handshake fails then there are several possible causes, if it is +nothing obvious like no client certificate then the B<-bugs>, +B<-ssl3>, B<-tls1>, B<-no_ssl3>, B<-no_tls1> options can be tried +in case it is a buggy server. In particular you should play with these +options B<before> submitting a bug report to an OpenSSL mailing list. + +A frequent problem when attempting to get client certificates working +is that a web client complains it has no certificates or gives an empty +list to choose from. This is normally because the server is not sending +the clients certificate authority in its "acceptable CA list" when it +requests a certificate. By using B<s_client> the CA list can be viewed +and checked. However some servers only request client authentication +after a specific URL is requested. To obtain the list in this case it +is necessary to use the B<-prexit> option and send an HTTP request +for an appropriate page. + +If a certificate is specified on the command line using the B<-cert> +option it will not be used unless the server specifically requests +a client certificate. Therefor merely including a client certificate +on the command line is no guarantee that the certificate works. + +If there are problems verifying a server certificate then the +B<-showcerts> option can be used to show the whole chain. + +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 the +techniques used are rather old, the C source of B<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<-prexit> option is a bit of a hack. We should really report +information whenever a session is renegotiated. + +=head1 SEE ALSO + +L<SSL_CONF_cmd(3)>, +L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)> + +=head1 HISTORY + +The -no_alt_chains options was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/s_server.pod b/openssl-1.1.0h/doc/apps/s_server.pod new file mode 100644 index 0000000..e8ec91b --- /dev/null +++ b/openssl-1.1.0h/doc/apps/s_server.pod @@ -0,0 +1,616 @@ +=pod + +=head1 NAME + +openssl-s_server, +s_server - SSL/TLS server program + +=head1 SYNOPSIS + +B<openssl> B<s_server> +[B<-help>] +[B<-port port>] +[B<-accept val>] +[B<-naccept count>] +[B<-unix val>] +[B<-unlink>] +[B<-4>] +[B<-6>] +[B<-context id>] +[B<-verify depth>] +[B<-Verify depth>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-cert filename>] +[B<-certform DER|PEM>] +[B<-key keyfile>] +[B<-keyform DER|PEM>] +[B<-pass arg>] +[B<-dcert filename>] +[B<-dcertform DER|PEM>] +[B<-dkey keyfile>] +[B<-dkeyform DER|PEM>] +[B<-dpass arg>] +[B<-dhparam filename>] +[B<-nbio>] +[B<-nbio_test>] +[B<-crlf>] +[B<-debug>] +[B<-msg>] +[B<-state>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-no_check_time>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level num>] +[B<-verify_depth num>] +[B<-verify_return_error>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-nocert>] +[B<-client_sigalgs sigalglist>] +[B<-named_curve curve>] +[B<-cipher cipherlist>] +[B<-serverpref>] +[B<-quiet>] +[B<-ssl3>] +[B<-tls1>] +[B<-tls1_1>] +[B<-tls1_2>] +[B<-dtls>] +[B<-dtls1>] +[B<-dtls1_2>] +[B<-listen>] +[B<-async>] +[B<-split_send_frag>] +[B<-max_pipelines>] +[B<-read_buf>] +[B<-no_ssl3>] +[B<-no_tls1>] +[B<-no_tls1_1>] +[B<-no_tls1_2>] +[B<-no_dhe>] +[B<-bugs>] +[B<-comp>] +[B<-no_comp>] +[B<-brief>] +[B<-www>] +[B<-WWW>] +[B<-HTTP>] +[B<-engine id>] +[B<-tlsextdebug>] +[B<-no_ticket>] +[B<-id_prefix arg>] +[B<-rand file(s)>] +[B<-serverinfo file>] +[B<-no_resumption_on_reneg>] +[B<-status>] +[B<-status_verbose>] +[B<-status_timeout nsec>] +[B<-status_url url>] +[B<-alpn protocols>] +[B<-nextprotoneg protocols>] + +=head1 DESCRIPTION + +The B<s_server> command implements a generic SSL/TLS server which listens +for connections on a given port using SSL/TLS. + +=head1 OPTIONS + +In addition to the options below the B<s_server> utility also supports the +common and server only options documented in the +in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)> +manual page. + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-port port> + +The TCP port to listen on for connections. If not specified 4433 is used. + +=item B<-accept val> + +The optional TCP host and port to listen on for connections. If not specified, *:4433 is used. + +=item B<-naccept count> + +The server will exit after receiving B<number> connections, default unlimited. + +=item B<-unix val> + +Unix domain socket to accept on. + +=item B<-unlink> + +For -unix, unlink existing socket first. + +=item B<-4> + +Use IPv4 only. + +=item B<-6> + +Use IPv6 only. + +=item B<-context id> + +Sets the SSL context id. It can be given any string value. If this option +is not present a default value will be used. + +=item B<-cert certname> + +The certificate to use, most servers cipher suites require the use of a +certificate and some require a certificate with a certain public key type: +for example the DSS cipher suites require a certificate containing a DSS +(DSA) key. If not specified then the filename "server.pem" will be used. + +=item B<-certform format> + +The certificate format to use: DER or PEM. PEM is the default. + +=item B<-key keyfile> + +The private key to use. If not specified then the certificate file will +be used. + +=item B<-keyform format> + +The private format to use: DER or PEM. PEM is the default. + +=item B<-pass arg> + +The private key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-dcert filename>, B<-dkey keyname> + +Specify an additional certificate and private key, these behave in the +same manner as the B<-cert> and B<-key> options except there is no default +if they are not specified (no additional certificate and key is used). As +noted above some cipher suites require a certificate containing a key of +a certain type. Some cipher suites need a certificate carrying an RSA key +and some a DSS (DSA) key. By using RSA and DSS certificates and keys +a server can support clients which only support RSA or DSS cipher suites +by using an appropriate certificate. + +=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg> + +Additional certificate and private key format and passphrase respectively. + +=item B<-nocert> + +If this option is set then no certificate is used. This restricts the +cipher suites available to the anonymous ones (currently just anonymous +DH). + +=item B<-dhparam filename> + +The DH parameter file to use. The ephemeral DH cipher suites generate keys +using a set of DH parameters. If not specified then an attempt is made to +load the parameters from the server certificate file. +If this fails then a static set of parameters hard coded into the B<s_server> +program will be used. + +=item B<-no_dhe> + +If this option is set then no DH parameters will be loaded effectively +disabling the ephemeral DH cipher suites. + +=item B<-crl_check>, B<-crl_check_all> + +Check the peer certificate has not been revoked by its CA. +The CRL(s) are appended to the certificate file. With the B<-crl_check_all> +option all CRLs of all CAs in the chain are checked. + +=item B<-CApath directory> + +The directory to use for client certificate verification. This directory +must be in "hash format", see B<verify> for more information. These are +also used when building the server certificate chain. + +=item B<-CAfile file> + +A file containing trusted certificates to use during client authentication +and to use when attempting to build the server certificate chain. The list +is also used in the list of acceptable client CAs passed to the client when +a certificate is requested. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-verify depth>, B<-Verify depth> + +The verify depth to use. This specifies the maximum length of the +client certificate chain and makes the server request a certificate from +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<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, +B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, +B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>, +B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, +B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, +B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, +B<-verify_ip>, B<-verify_name>, B<-x509_strict> + +Set different peer certificate verification options. +See the L<verify(1)> manual page for details. + +=item B<-verify_return_error> + +Verification errors normally just print a message but allow the +connection to continue, for debugging purposes. +If this option is used, then verification errors close the connection. + +=item B<-state> + +Prints the SSL session states. + +=item B<-debug> + +Print extensive debugging information including a hex dump of all traffic. + +=item B<-msg> + +Show all protocol messages with hex dump. + +=item B<-trace> + +Show verbose trace output of protocol messages. OpenSSL needs to be compiled +with B<enable-ssl-trace> for this option to work. + +=item B<-msgfile> + +File to send output of B<-msg> or B<-trace> to, default standard output. + +=item B<-nbio_test> + +Tests non blocking I/O + +=item B<-nbio> + +Turns on non blocking I/O + +=item B<-crlf> + +This option translated a line feed from the terminal into CR+LF. + +=item B<-quiet> + +Inhibit printing of session and certificate information. + +=item B<-psk_hint hint> + +Use the PSK identity hint B<hint> when using a PSK cipher suite. + +=item B<-psk key> + +Use the PSK key B<key> when using a PSK cipher suite. The key is +given as a hexadecimal number without leading 0x, for example -psk +1a2b3c4d. +This option must be provided in order to use a PSK cipher. + +=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> + +These options require or disable the use of the specified SSL or TLS protocols. +By default B<s_server> will negotiate the highest mutually supported protocol +version. +When a specific TLS version is required, only that version will be accepted +from the client. + +=item B<-dtls>, B<-dtls1>, B<-dtls1_2> + +These options make B<s_server> use DTLS protocols instead of TLS. +With B<-dtls>, B<s_server> will negotiate any supported DTLS protocol version, +whilst B<-dtls1> and B<-dtls1_2> will only support DTLSv1.0 and DTLSv1.2 +respectively. + +=item B<-listen> + +This option can only be used in conjunction with one of the DTLS options above. +With this option B<s_server> will listen on a UDP port for incoming connections. +Any ClientHellos that arrive will be checked to see if they have a cookie in +them or not. +Any without a cookie will be responded to with a HelloVerifyRequest. +If a ClientHello with a cookie is received then B<s_server> will connect to +that peer and complete the handshake. + +=item B<-async> + +Switch on asynchronous mode. Cryptographic operations will be performed +asynchronously. This will only have an effect if an asynchronous capable engine +is also used via the B<-engine> option. For test purposes the dummy async engine +(dasync) can be used (if available). + +=item B<-split_send_frag int> + +The size used to split data for encrypt pipelines. If more data is written in +one go than this value then it will be split into multiple pipelines, up to the +maximum number of pipelines defined by max_pipelines. This only has an effect if +a suitable ciphersuite has been negotiated, an engine that supports pipelining +has been loaded, and max_pipelines is greater than 1. See +L<SSL_CTX_set_split_send_fragment(3)> for further information. + +=item B<-max_pipelines int> + +The maximum number of encrypt/decrypt pipelines to be used. This will only have +an effect if an engine has been loaded that supports pipelining (e.g. the dasync +engine) and a suitable ciphersuite has been negotiated. The default value is 1. +See L<SSL_CTX_set_max_pipelines(3)> for further information. + +=item B<-read_buf int> + +The default read buffer size to be used for connections. This will only have an +effect if the buffer size is larger than the size that would otherwise be used +and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for +further information). + +=item B<-bugs> + +There are several known bug in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-comp> + +Enable negotiation of TLS compression. +This option was introduced in OpenSSL 1.1.0. +TLS compression is not recommended and is off by default as of +OpenSSL 1.1.0. + +=item B<-no_comp> + +Disable negotiation of TLS compression. +TLS compression is not recommended and is off by default as of +OpenSSL 1.1.0. + +=item B<-brief> + +Provide a brief summary of connection parameters instead of the normal verbose +output. + +=item B<-client_sigalgs sigalglist> + +Signature algorithms to support for client certificate authentication +(colon-separated list) + +=item B<-named_curve curve> + +Specifies the elliptic curve to use. NOTE: this is single curve, not a list. +For a list of all possible curves, use: + + $ openssl ecparam -list_curves + +=item B<-cipher cipherlist> + +This allows the cipher list used by the server to be modified. When +the client sends a list of supported ciphers the first client cipher +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 a hex dump of any TLS extensions received from the server. + +=item B<-no_ticket> + +Disable RFC4507bis session ticket support. + +=item B<-www> + +Sends a status message back to the client when it connects. This includes +information about the ciphers used and various session parameters. +The output is in HTML format so this option will normally be used with a +web browser. + +=item B<-WWW> + +Emulates a simple web server. Pages will be resolved relative to the +current directory, for example if the URL https://myhost/page.html is +requested the file ./page.html will be loaded. + +=item B<-HTTP> + +Emulates a simple web server. Pages will be resolved relative to the +current directory, for example if the URL https://myhost/page.html is +requested the file ./page.html will be loaded. The files loaded are +assumed to contain a complete and correct HTTP response (lines that +are part of the HTTP response line and headers must end with CRLF). + +=item B<-rev> + +Simple test server which just reverses the text received from the client +and sends it back to the server. Also sets B<-brief>. + +=item B<-engine id> + +Specifying an engine (by its unique B<id> string) will cause B<s_server> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-id_prefix arg> + +Generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful +for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple +servers, when each of which might be generating a unique range of session +IDs (eg. with a certain prefix). + +=item B<-rand file(s)> + +A file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<-serverinfo file> + +A file containing one or more blocks of PEM data. Each PEM block +must encode a TLS ServerHello extension (2 bytes type, 2 bytes length, +followed by "length" bytes of extension data). If the client sends +an empty TLS ClientHello extension matching the type, the corresponding +ServerHello extension will be returned. + +=item B<-no_resumption_on_reneg> + +Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option. + +=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<-alpn protocols>, B<-nextprotoneg protocols> + +these flags enable the +Enable the Application-Layer Protocol Negotiation or Next Protocol +Negotiation extension, respectively. ALPN is the IETF standard and +replaces NPN. +The B<protocols> list is 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 + +If a connection request is established with an SSL client and neither the +B<-www> nor the B<-WWW> option has been used then normally any data received +from the client is displayed and any key presses will be sent to the client. + +Certain single letter commands are also recognized which perform special +operations: these are listed below. + +=over 4 + +=item B<q> + +end the current SSL connection but still accept new connections. + +=item B<Q> + +end the current SSL connection and exit. + +=item B<r> + +renegotiate the SSL session. + +=item B<R> + +renegotiate the SSL session and request a client certificate. + +=item B<P> + +send some plain text down the underlying TCP connection: this should +cause the client to disconnect due to a protocol violation. + +=item B<S> + +print out some session cache status information. + +=back + +=head1 NOTES + +B<s_server> can be used to debug SSL clients. To accept connections from +a web browser the command: + + openssl s_server -accept 443 -www + +can be used for example. + +Although specifying an empty list of CAs when requesting a client certificate +is strictly speaking a protocol violation, some SSL clients interpret this to +mean any CA is acceptable. This is useful for debugging purposes. + +The session parameters can printed out using the B<sess_id> program. + +=head1 BUGS + +Because this program has a lot of options and also because some of the +techniques used are rather old, the C source of B<s_server> is rather hard to +read and not a model of how things should be done. +A typical SSL server program would be much simpler. + +The output of common ciphers is wrong: it just gives the list of ciphers that +OpenSSL recognizes and the client supports. + +There should be a way for the B<s_server> program to print out details of any +unknown cipher suites a client says it supports. + +=head1 SEE ALSO + +L<SSL_CONF_cmd(3)>, +L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)> + +=head1 HISTORY + +The -no_alt_chains options was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/s_time.pod b/openssl-1.1.0h/doc/apps/s_time.pod new file mode 100644 index 0000000..d44dd93 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/s_time.pod @@ -0,0 +1,195 @@ +=pod + +=head1 NAME + +openssl-s_time, +s_time - SSL/TLS performance timing program + +=head1 SYNOPSIS + +B<openssl> B<s_time> +[B<-help>] +[B<-connect host:port>] +[B<-www page>] +[B<-cert filename>] +[B<-key filename>] +[B<-CApath directory>] +[B<-CAfile filename>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-reuse>] +[B<-new>] +[B<-verify depth>] +[B<-nbio>] +[B<-time seconds>] +[B<-ssl3>] +[B<-bugs>] +[B<-cipher cipherlist>] + +=head1 DESCRIPTION + +The B<s_time> command implements a generic SSL/TLS client which connects to a +remote host using SSL/TLS. It can request a page from the server and includes +the time to transfer the payload data in its timing measurements. It measures +the number of connections within a given timeframe, the amount of data +transferred (if any), and calculates the average time spent for one connection. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-connect host:port> + +This specifies the host and optional port to connect to. + +=item B<-www page> + +This specifies the page to GET from the server. A value of '/' gets the +index.htm[l] page. If this parameter is not specified, then B<s_time> will only +perform the handshake to establish SSL connections but not transfer any +payload data. + +=item B<-cert certname> + +The certificate to use, if one is requested by the server. The default is +not to use a certificate. The file is in PEM format. + +=item B<-key keyfile> + +The private key to use. If not specified then the certificate file will +be used. The file is in PEM format. + +=item B<-verify depth> + +The verify depth to use. This specifies the maximum length of the +server certificate chain and turns on server certificate verification. +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<-CApath directory> + +The directory to use for server certificate verification. This directory +must be in "hash format", see B<verify> for more information. These are +also used when building the client certificate chain. + +=item B<-CAfile file> + +A file containing trusted certificates to use during server authentication +and to use when attempting to build the client certificate chain. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-new> + +performs the timing test using a new session ID for each connection. +If neither B<-new> nor B<-reuse> are specified, they are both on by default +and executed in sequence. + +=item B<-reuse> + +performs the timing test using the same session ID; this can be used as a test +that session caching is working. If neither B<-new> nor B<-reuse> are +specified, they are both on by default and executed in sequence. + +=item B<-nbio> + +turns on non-blocking I/O. + +=item B<-ssl3> + +these options disable the use of certain SSL or TLS protocols. By default +the initial handshake uses a method which should be compatible with all +servers and permit them to use SSL v3 or TLS as appropriate. +The timing program is not as rich in options to turn protocols on and off as +the L<s_client(1)> program and may not connect to all servers. + +Unfortunately there are a lot of ancient and broken servers in use which +cannot handle this technique and will fail to connect. Some servers only +work if TLS is turned off with the B<-ssl3> option. + +=item B<-bugs> + +there are several known bug in SSL and TLS implementations. Adding this +option enables various workarounds. + +=item B<-cipher cipherlist> + +this allows the cipher list sent by the client to be modified. Although +the server determines which cipher suite is used it should take the first +supported cipher in the list sent by the client. +See the L<ciphers(1)> command for more information. + +=item B<-time length> + +specifies how long (in seconds) B<s_time> should establish connections and +optionally transfer payload data from a server. Server and client performance +and the link speed determine how many connections B<s_time> can establish. + +=back + +=head1 NOTES + +B<s_time> can be used to measure the performance of an SSL connection. +To connect to an SSL HTTP server and get the default page the command + + openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3] + +would typically be used (https uses port 443). 'commoncipher' is a cipher to +which both client and server can agree, see the L<ciphers(1)> command +for details. + +If the handshake fails then there are several possible causes, if it is +nothing obvious like no client certificate then the B<-bugs> and +B<-ssl3> options can be tried +in case it is a buggy server. In particular you should play with these +options B<before> submitting a bug report to an OpenSSL mailing list. + +A frequent problem when attempting to get client certificates working +is that a web client complains it has no certificates or gives an empty +list to choose from. This is normally because the server is not sending +the clients certificate authority in its "acceptable CA list" when it +requests a certificate. By using L<s_client(1)> the CA list can be +viewed and checked. However some servers only request client authentication +after a specific URL is requested. To obtain the list in this case it +is necessary to use the B<-prexit> option of L<s_client(1)> and +send an HTTP request for an appropriate page. + +If a certificate is specified on the command line using the B<-cert> +option it will not be used unless the server specifically requests +a client certificate. Therefor merely including a client certificate +on the command line is no guarantee that the certificate works. + +=head1 BUGS + +Because this program does not have all the options of the +L<s_client(1)> program to turn protocols on and off, you may not be +able to measure the performance of all protocols with all servers. + +The B<-verify> option should really exit if the server verification +fails. + +=head1 SEE ALSO + +L<s_client(1)>, L<s_server(1)>, L<ciphers(1)> + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/sess_id.pod b/openssl-1.1.0h/doc/apps/sess_id.pod new file mode 100644 index 0000000..7766c71 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/sess_id.pod @@ -0,0 +1,164 @@ +=pod + +=head1 NAME + +openssl-sess_id, +sess_id - SSL/TLS session handling utility + +=head1 SYNOPSIS + +B<openssl> B<sess_id> +[B<-help>] +[B<-inform PEM|DER>] +[B<-outform PEM|DER|NSS>] +[B<-in filename>] +[B<-out filename>] +[B<-text>] +[B<-noout>] +[B<-context ID>] + +=head1 DESCRIPTION + +The B<sess_id> process the encoded version of the SSL session structure +and optionally prints out SSL session details (for example the SSL session +master key) in human readable format. Since this is a diagnostic tool that +needs some knowledge of the SSL protocol to use properly, most users will +not need to use it. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM> + +This specifies the input format. The B<DER> option uses an ASN1 DER encoded +format containing session details. The precise format can vary from one version +to the next. The B<PEM> form is the default format: it consists of the B<DER> +format base64 encoded with additional header and footer lines. + +=item B<-outform DER|PEM|NSS> + +This specifies the output format. The B<PEM> and B<DER> options have the same meaning +as the B<-inform> option. The B<NSS> option outputs the session id and the master key +in NSS keylog format. + +=item B<-in filename> + +This specifies the input filename to read session information from or standard +input by default. + +=item B<-out filename> + +This specifies the output filename to write session information to or standard +output if this option is not specified. + +=item B<-text> + +prints out the various public or private key components in +plain text in addition to the encoded version. + +=item B<-cert> + +if a certificate is present in the session it will be output using this option, +if the B<-text> option is also present then it will be printed out in text form. + +=item B<-noout> + +this option prevents output of the encoded version of the session. + +=item B<-context ID> + +this option can set the session id so the output session information uses the +supplied ID. The ID can be any string of characters. This option won't normally +be used. + +=back + +=head1 OUTPUT + +Typical output: + + SSL-Session: + Protocol : TLSv1 + Cipher : 0016 + Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED + Session-ID-ctx: 01000000 + Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD + Key-Arg : None + Start Time: 948459261 + Timeout : 300 (sec) + Verify return code 0 (ok) + +Theses are described below in more detail. + +=over 4 + +=item B<Protocol> + +this is the protocol in use TLSv1.2, TLSv1.1, TLSv1 or SSLv3. + +=item B<Cipher> + +the cipher used this is the actual raw SSL or TLS cipher code, see the SSL +or TLS specifications for more information. + +=item B<Session-ID> + +the SSL session ID in hex format. + +=item B<Session-ID-ctx> + +the session ID context in hex format. + +=item B<Master-Key> + +this is the SSL session master key. + +=item B<Start Time> + +this is the session start time represented as an integer in standard Unix format. + +=item B<Timeout> + +the timeout in seconds. + +=item B<Verify return code> + +this is the return code when an SSL client certificate is verified. + +=back + +=head1 NOTES + +The PEM encoded session format uses the header and footer lines: + + -----BEGIN SSL SESSION PARAMETERS----- + -----END SSL SESSION PARAMETERS----- + +Since the SSL session output contains the master key it is possible to read the contents +of an encrypted session using this information. Therefore appropriate security precautions +should be taken if the information is being output by a "real" application. This is +however strongly discouraged and should only be used for debugging purposes. + +=head1 BUGS + +The cipher and start time should be printed out in human readable form. + +=head1 SEE ALSO + +L<ciphers(1)>, L<s_server(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/smime.pod b/openssl-1.1.0h/doc/apps/smime.pod new file mode 100644 index 0000000..753e275 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/smime.pod @@ -0,0 +1,518 @@ +=pod + +=head1 NAME + +openssl-smime, +smime - S/MIME utility + +=head1 SYNOPSIS + +B<openssl> B<smime> +[B<-help>] +[B<-encrypt>] +[B<-decrypt>] +[B<-sign>] +[B<-resign>] +[B<-verify>] +[B<-pk7out>] +[B<-binary>] +[B<-crlfeol>] +[B<-[cipher]>] +[B<-in file>] +[B<-CAfile file>] +[B<-CApath dir>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-use_deltas>] +[B<-auth_level num>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-certfile file>] +[B<-signer file>] +[B<-recip file>] +[B<-inform SMIME|PEM|DER>] +[B<-passin arg>] +[B<-inkey file_or_id>] +[B<-out file>] +[B<-outform SMIME|PEM|DER>] +[B<-content file>] +[B<-to addr>] +[B<-from ad>] +[B<-subject s>] +[B<-text>] +[B<-indef>] +[B<-noindef>] +[B<-stream>] +[B<-rand file(s)>] +[B<-md digest>] +[cert.pem]... + +=head1 DESCRIPTION + +The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and +verify S/MIME messages. + +=head1 OPTIONS + +There are six operation options that set the type of operation to be performed. +The meaning of the other options varies according to the operation type. + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-encrypt> + +encrypt mail for the given recipient certificates. Input file is the message +to be encrypted. The output file is the encrypted mail in MIME format. + +Note that no revocation check is done for the recipient cert, so if that +key has been compromised, others may be able to decrypt the text. + +=item B<-decrypt> + +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<-sign> + +sign mail using the supplied certificate and private key. Input file is +the message to be signed. The signed message in MIME format is written +to the output file. + +=item B<-verify> + +verify signed mail. Expects a signed mail message on input and outputs +the signed data. Both clear text and opaque signing is supported. + +=item B<-pk7out> + +takes an input message and writes out a PEM encoded PKCS#7 structure. + +=item B<-resign> + +resign a message: take an existing message and one or more new signers. + +=item B<-in filename> + +the input message to be encrypted or signed or the MIME message to +be decrypted or verified. + +=item B<-inform SMIME|PEM|DER> + +this specifies the input format for the PKCS#7 structure. The default +is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER> +format change this to expect PEM and DER format PKCS#7 structures +instead. This currently only affects the input format of the PKCS#7 +structure, if no PKCS#7 structure is being input (for example with +B<-encrypt> or B<-sign>) this option has no effect. + +=item B<-out filename> + +the message text that has been decrypted or verified or the output MIME +format message that has been signed or verified. + +=item B<-outform SMIME|PEM|DER> + +this specifies the output format for the PKCS#7 structure. The default +is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER> +format change this to write PEM and DER format PKCS#7 structures +instead. This currently only affects the output format of the PKCS#7 +structure, if no PKCS#7 structure is being output (for example with +B<-verify> or B<-decrypt>) this option has no effect. + +=item B<-stream -indef -noindef> + +the B<-stream> and B<-indef> options are equivalent and enable streaming I/O +for encoding operations. This permits single pass processing of data without +the need to hold the entire contents in memory, potentially supporting very +large files. Streaming is automatically set for S/MIME signing with detached +data if the output format is B<SMIME> it is currently off by default for all +other operations. + +=item B<-noindef> + +disable streaming I/O where it would produce and indefinite length constructed +encoding. This option currently has no effect. In future streaming will be +enabled by default on all relevant operations and this option will disable it. + +=item B<-content filename> + +This specifies a file containing the detached content, this is only +useful with the B<-verify> command. This is only usable if the PKCS#7 +structure is using the detached signature form where the content is +not included. This option will override any content if the input format +is S/MIME and it uses the multipart/signed MIME content type. + +=item B<-text> + +this option adds plain text (text/plain) MIME headers to the supplied +message if encrypting or signing. If decrypting or verifying it strips +off text headers: if the decrypted or verified message is not of MIME +type text/plain then an error occurs. + +=item B<-CAfile file> + +a file containing trusted CA certificates, only used with B<-verify>. + +=item B<-CApath dir> + +a directory containing trusted CA certificates, only used with +B<-verify>. This directory must be a standard certificate directory: that +is a hash of each subject name (using B<x509 -hash>) should be linked +to each certificate. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-md digest> + +digest algorithm to use when signing or resigning. If not present then the +default digest algorithm for the signing key will be used (usually SHA1). + +=item B<-[cipher]> + +the encryption algorithm to use. For example DES (56 bits) - B<-des>, +triple DES (168 bits) - B<-des3>, +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 triple DES is used. Only used with B<-encrypt>. + +=item B<-nointern> + +when verifying a message normally certificates (if any) included in +the message are searched for the signing certificate. With this option +only the certificates specified in the B<-certfile> option are used. +The supplied certificates can still be used as untrusted CAs however. + +=item B<-noverify> + +do not verify the signers certificate of a signed message. + +=item B<-nochain> + +do not do chain verification of signers certificates: that is don't +use the certificates in the signed message as untrusted CAs. + +=item B<-nosigs> + +don't try to verify the signatures on the message. + +=item B<-nocerts> + +when signing a message the signer's certificate is normally included +with this option it is excluded. This will reduce the size of the +signed message but the verifier must have a copy of the signers certificate +available locally (passed using the B<-certfile> option for example). + +=item B<-noattr> + +normally when a message is signed a set of attributes are included which +include the signing time and supported symmetric algorithms. With this +option they are not included. + +=item B<-binary> + +normally the input message is converted to "canonical" format which is +effectively using CR and LF as end of line: as required by the S/MIME +specification. When this option is present no translation occurs. This +is useful when handling binary data which may not be in MIME format. + +=item B<-crlfeol> + +normally the output file uses a single B<LF> as end of line. When this +option is present B<CRLF> is used instead. + +=item B<-nodetach> + +when signing a message use opaque signing: this form is more resistant +to translation by mail relays but it cannot be read by mail agents that +do not support S/MIME. Without this option cleartext signing with +the MIME type multipart/signed is used. + +=item B<-certfile file> + +allows additional certificates to be specified. When signing these will +be included with the message. When verifying these will be searched for +the signers certificates. The certificates should be in PEM format. + +=item B<-signer file> + +a signing certificate when signing or resigning a message, this option can be +used multiple times if more than one signer is required. If a message is being +verified then the signers certificates will be written to this file if the +verification was successful. + +=item B<-recip file> + +the recipients certificate when decrypting a message. This certificate +must match one of the recipients of the message or an error occurs. + +=item B<-inkey file_or_id> + +the private key to use when signing or decrypting. This must match the +corresponding certificate. If this option is not specified then the +private key must be included in the certificate file specified with +the B<-recip> or B<-signer> file. When signing this option can be used +multiple times to specify successive keys. +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. + +=item B<-passin arg> + +the private key password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L<RAND_egd(3)>). +Multiple files can be specified separated by an OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + +=item B<cert.pem...> + +one or more certificates of message recipients: used when encrypting +a message. + +=item B<-to, -from, -subject> + +the relevant mail headers. These are included outside the signed +portion of a message so they may be included manually. If signing +then many S/MIME mail clients check the signers certificate's email +address matches that specified in the From: address. + +=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>, +B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>, +B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>, +B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>, +B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, +B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, +B<-verify_ip>, B<-verify_name>, B<-x509_strict> + +Set various options of certificate chain verification. See +L<verify(1)> manual page for details. + +=back + +=head1 NOTES + +The MIME message must be sent without any blank lines between the +headers and the output. Some mail programs will automatically add +a blank line. Piping the mail directly to sendmail is one way to +achieve the correct format. + +The supplied message to be signed or encrypted must include the +necessary MIME headers or many S/MIME clients won't display it +properly (if at all). You can use the B<-text> option to automatically +add plain text headers. + +A "signed and encrypted" message is one where a signed message is +then encrypted. This can be produced by encrypting an already signed +message: see the examples section. + +This version of the program only allows one signer per message but it +will verify multiple signers on received messages. Some S/MIME clients +choke if a message contains multiple signers. It is possible to sign +messages "in parallel" by signing an already signed message. + +The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME +clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7 +encrypted data is used for other purposes. + +The B<-resign> option uses an existing message digest when adding a new +signer. This means that attributes must be present in at least one existing +signer using the same message digest or this operation will fail. + +The B<-stream> and B<-indef> options enable streaming I/O support. +As a result the encoding is BER using indefinite length constructed encoding +and no longer DER. Streaming is supported for the B<-encrypt> operation and the +B<-sign> operation if the content is not detached. + +Streaming is always used for the B<-sign> operation with detached data but +since the content is no longer part of the PKCS#7 structure the encoding +remains DER. + +=head1 EXIT CODES + +=over 4 + +=item Z<>0 + +the operation was completely successfully. + +=item Z<>1 + +an error occurred parsing the command options. + +=item Z<>2 + +one of the input files could not be read. + +=item Z<>3 + +an error occurred creating the PKCS#7 file or when reading the MIME +message. + +=item Z<>4 + +an error occurred decrypting or verifying the message. + +=item Z<>5 + +the message was verified correctly but an error occurred writing out +the signers certificates. + +=back + +=head1 EXAMPLES + +Create a cleartext signed message: + + openssl smime -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem + +Create an opaque signed message: + + openssl smime -sign -in message.txt -text -out mail.msg -nodetach \ + -signer mycert.pem + +Create a signed message, include some additional certificates and +read the private key from another file: + + openssl smime -sign -in in.txt -text -out mail.msg \ + -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem + +Create a signed message with two signers: + + openssl smime -sign -in message.txt -text -out mail.msg \ + -signer mycert.pem -signer othercert.pem + +Send a signed message under Unix directly to sendmail, including headers: + + openssl smime -sign -in in.txt -text -signer mycert.pem \ + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed message" | sendmail someone@somewhere + +Verify a message and extract the signer's certificate if successful: + + openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt + +Send encrypted mail using triple DES: + + openssl smime -encrypt -in in.txt -from steve@openssl.org \ + -to someone@somewhere -subject "Encrypted message" \ + -des3 user.pem -out mail.msg + +Sign and encrypt mail: + + openssl smime -sign -in ml.txt -signer my.pem -text \ + | openssl smime -encrypt -out mail.msg \ + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed and Encrypted message" -des3 user.pem + +Note: the encryption command does not include the B<-text> option because the +message being encrypted already has MIME headers. + +Decrypt mail: + + openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem + +The output from Netscape form signing is a PKCS#7 structure with the +detached signature format. You can use this program to verify the +signature by line wrapping the base64 encoded structure and surrounding +it with: + + -----BEGIN PKCS7----- + -----END PKCS7----- + +and using the command: + + openssl smime -verify -inform PEM -in signature.pem -content content.txt + +Alternatively you can base64 decode the signature and use: + + openssl smime -verify -inform DER -in signature.der -content content.txt + +Create an encrypted message using 128 bit Camellia: + + openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem + +Add a signer to an existing message: + + openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg + +=head1 BUGS + +The MIME parser isn't very clever: it seems to handle most messages that I've +thrown at it but it may choke on others. + +The code currently will only write out the signer's certificate to a file: if +the signer has a separate encryption certificate this must be manually +extracted. There should be some heuristic that determines the correct +encryption certificate. + +Ideally a database should be maintained of a certificates for each email +address. + +The code doesn't currently take note of the permitted symmetric encryption +algorithms as supplied in the SMIMECapabilities signed attribute. This means the +user has to manually include the correct encryption algorithm. It should store +the list of permitted ciphers in a database and only use those. + +No revocation checking is done on the signer's certificate. + +The current code can only handle S/MIME v2 messages, the more complex S/MIME v3 +structures may cause parsing errors. + +=head1 HISTORY + +The use of multiple B<-signer> options and the B<-resign> command were first +added in OpenSSL 1.0.0 + +The -no_alt_chains options was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/speed.pod b/openssl-1.1.0h/doc/apps/speed.pod new file mode 100644 index 0000000..4379319 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/speed.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +openssl-speed, +speed - test library performance + +=head1 SYNOPSIS + +B<openssl speed> +[B<-help>] +[B<-engine id>] +[B<-elapsed>] +[B<-evp algo>] +[B<-decrypt>] +[B<algorithm...>] + +=head1 DESCRIPTION + +This command is used to test the performance of cryptographic algorithms. +To see the list of supported algorithms, use the I<list --digest-commands> +or I<list --cipher-commands> command. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<speed> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=item B<-elapsed> + +Measure time in real time instead of CPU time. It can be useful when testing +speed of hardware engines. + +=item B<-evp algo> + +Use the specified cipher or message digest algorithm via the EVP interface. + +=item B<-decrypt> + +Time the decryption instead of encryption. Affects only the EVP testing. + +=item B<[zero or more test algorithms]> + +If any options are given, B<speed> tests those algorithms, otherwise all of +the above are tested. + +=back + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/spkac.pod b/openssl-1.1.0h/doc/apps/spkac.pod new file mode 100644 index 0000000..e337e4e --- /dev/null +++ b/openssl-1.1.0h/doc/apps/spkac.pod @@ -0,0 +1,148 @@ +=pod + +=head1 NAME + +openssl-spkac, +spkac - SPKAC printing and generating utility + +=head1 SYNOPSIS + +B<openssl> B<spkac> +[B<-help>] +[B<-in filename>] +[B<-out filename>] +[B<-key keyfile>] +[B<-passin arg>] +[B<-challenge string>] +[B<-pubkey>] +[B<-spkac spkacname>] +[B<-spksect section>] +[B<-noout>] +[B<-verify>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<spkac> command processes Netscape signed public key and challenge +(SPKAC) files. It can print out their contents, verify the signature and +produce its own SPKACs from a supplied private key. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-in filename> + +This specifies the input filename to read from or standard input if this +option is not specified. Ignored if the B<-key> option is used. + +=item B<-out filename> + +specifies the output filename to write to or standard output by +default. + +=item B<-key keyfile> + +create an SPKAC file using the private key in B<keyfile>. The +B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if +present. + +=item B<-passin password> + +the input file password source. For more information about the format of B<arg> +see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. + +=item B<-challenge string> + +specifies the challenge string if an SPKAC is being created. + +=item B<-spkac spkacname> + +allows an alternative name form the variable containing the +SPKAC. The default is "SPKAC". This option affects both +generated and input SPKAC files. + +=item B<-spksect section> + +allows an alternative name form the section containing the +SPKAC. The default is the default section. + +=item B<-noout> + +don't output the text version of the SPKAC (not used if an +SPKAC is being created). + +=item B<-pubkey> + +output the public key of an SPKAC (not used if an SPKAC is +being created). + +=item B<-verify> + +verifies the digital signature on the supplied SPKAC. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<spkac> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head1 EXAMPLES + +Print out the contents of an SPKAC: + + openssl spkac -in spkac.cnf + +Verify the signature of an SPKAC: + + openssl spkac -in spkac.cnf -noout -verify + +Create an SPKAC using the challenge string "hello": + + openssl spkac -key key.pem -challenge hello -out spkac.cnf + +Example of an SPKAC, (long lines split up for clarity): + + SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\ + PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\ + PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\ + 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\ + 4= + +=head1 NOTES + +A created SPKAC with suitable DN components appended can be fed into +the B<ca> utility. + +SPKACs are typically generated by Netscape when a form is submitted +containing the B<KEYGEN> tag as part of the certificate enrollment +process. + +The challenge string permits a primitive form of proof of possession +of private key. By checking the SPKAC signature and a random challenge +string some guarantee is given that the user knows the private key +corresponding to the public key being certified. This is important in +some applications. Without this it is possible for a previous SPKAC +to be used in a "replay attack". + +=head1 SEE ALSO + +L<ca(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/ts.pod b/openssl-1.1.0h/doc/apps/ts.pod new file mode 100644 index 0000000..0c949bf --- /dev/null +++ b/openssl-1.1.0h/doc/apps/ts.pod @@ -0,0 +1,662 @@ +=pod + +=head1 NAME + +openssl-ts, +ts - Time Stamping Authority tool (client/server) + +=head1 SYNOPSIS + +B<openssl> B<ts> +B<-query> +[B<-rand> file:file...] +[B<-config> configfile] +[B<-data> file_to_hash] +[B<-digest> digest_bytes] +[B<-[digest]>] +[B<-tspolicy> object_id] +[B<-no_nonce>] +[B<-cert>] +[B<-in> request.tsq] +[B<-out> request.tsq] +[B<-text>] + +B<openssl> B<ts> +B<-reply> +[B<-config> configfile] +[B<-section> tsa_section] +[B<-queryfile> request.tsq] +[B<-passin> password_src] +[B<-signer> tsa_cert.pem] +[B<-inkey> file_or_id] +[B<-sha1|-sha224|-sha256|-sha384|-sha512>] +[B<-chain> certs_file.pem] +[B<-tspolicy> object_id] +[B<-in> response.tsr] +[B<-token_in>] +[B<-out> response.tsr] +[B<-token_out>] +[B<-text>] +[B<-engine> id] + +B<openssl> B<ts> +B<-verify> +[B<-data> file_to_hash] +[B<-digest> digest_bytes] +[B<-queryfile> request.tsq] +[B<-in> response.tsr] +[B<-token_in>] +[B<-CApath> trusted_cert_path] +[B<-CAfile> trusted_certs.pem] +[B<-untrusted> cert_file.pem] +[I<verify options>] + +I<verify options:> +[-attime timestamp] +[-check_ss_sig] +[-crl_check] +[-crl_check_all] +[-explicit_policy] +[-extended_crl] +[-ignore_critical] +[-inhibit_any] +[-inhibit_map] +[-issuer_checks] +[-no_alt_chains] +[-no_check_time] +[-partial_chain] +[-policy arg] +[-policy_check] +[-policy_print] +[-purpose purpose] +[-suiteB_128] +[-suiteB_128_only] +[-suiteB_192] +[-trusted_first] +[-use_deltas] +[-auth_level num] +[-verify_depth num] +[-verify_email email] +[-verify_hostname hostname] +[-verify_ip ip] +[-verify_name name] +[-x509_strict] + +=head1 DESCRIPTION + +The B<ts> command is a basic Time Stamping Authority (TSA) client and server +application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A +TSA can be part of a PKI deployment and its role is to provide long +term proof of the existence of a certain datum before a particular +time. Here is a brief description of the protocol: + +=over 4 + +=item 1. + +The TSA client computes a one-way hash value for a data file and sends +the hash to the TSA. + +=item 2. + +The TSA attaches the current date and time to the received hash value, +signs them and sends the time stamp token back to the client. By +creating this token the TSA certifies the existence of the original +data file at the time of response generation. + +=item 3. + +The TSA client receives the time stamp token and verifies the +signature on it. It also checks if the token contains the same hash +value that it had sent to the TSA. + +=back + +There is one DER encoded protocol data unit defined for transporting a time +stamp request to the TSA and one for sending the time stamp response +back to the client. The B<ts> command has three main functions: +creating a time stamp request based on a data file, +creating a time stamp response based on a request, verifying if a +response corresponds to a particular request or a data file. + +There is no support for sending the requests/responses automatically +over HTTP or TCP yet as suggested in RFC 3161. The users must send the +requests either by ftp or e-mail. + +=head1 OPTIONS + +=head2 Time Stamp Request generation + +The B<-query> switch can be used for creating and printing a time stamp +request with the following options: + +=over 4 + +=item B<-rand> file:file... + +The files containing random data for seeding the random number +generator. Multiple files can be specified, the separator is B<;> for +MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) + +=item B<-config> configfile + +The configuration file to use. +Optional; for a description of the default value, +see L<openssl(1)/COMMAND SUMMARY>. + +=item B<-data> file_to_hash + +The data file for which the time stamp request needs to be +created. stdin is the default if neither the B<-data> nor the B<-digest> +parameter is specified. (Optional) + +=item B<-digest> digest_bytes + +It is possible to specify the message imprint explicitly without the data +file. The imprint must be specified in a hexadecimal format, two characters +per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or +1AF601...). The number of bytes must match the message digest algorithm +in use. (Optional) + +=item B<-[digest]> + +The message digest to apply to the data file. +Any digest supported by the OpenSSL B<dgst> command can be used. +The default is SHA-1. (Optional) + +=item B<-tspolicy> object_id + +The policy that the client expects the TSA to use for creating the +time stamp token. Either the dotted OID notation or OID names defined +in the config file can be used. If no policy is requested the TSA will +use its own default policy. (Optional) + +=item B<-no_nonce> + +No nonce is specified in the request if this option is +given. Otherwise a 64 bit long pseudo-random none is +included in the request. It is recommended to use nonce to +protect against replay-attacks. (Optional) + +=item B<-cert> + +The TSA is expected to include its signing certificate in the +response. (Optional) + +=item B<-in> request.tsq + +This option specifies a previously created time stamp request in DER +format that will be printed into the output file. Useful when you need +to examine the content of a request in human-readable +format. (Optional) + +=item B<-out> request.tsq + +Name of the output file to which the request will be written. Default +is stdout. (Optional) + +=item B<-text> + +If this option is specified the output is human-readable text format +instead of DER. (Optional) + +=back + +=head2 Time Stamp Response generation + +A time stamp response (TimeStampResp) consists of a response status +and the time stamp token itself (ContentInfo), if the token generation was +successful. The B<-reply> command is for creating a time stamp +response or time stamp token based on a request and printing the +response/token in human-readable format. If B<-token_out> is not +specified the output is always a time stamp response (TimeStampResp), +otherwise it is a time stamp token (ContentInfo). + +=over 4 + +=item B<-config> configfile + +The configuration file to use. +Optional; for a description of the default value, +see L<openssl(1)/COMMAND SUMMARY>. +See B<CONFIGURATION FILE OPTIONS> for configurable variables. + +=item B<-section> tsa_section + +The name of the config file section containing the settings for the +response generation. If not specified the default TSA section is +used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional) + +=item B<-queryfile> request.tsq + +The name of the file containing a DER encoded time stamp request. (Optional) + +=item B<-passin> password_src + +Specifies the password source for the private key of the TSA. See +B<PASS PHRASE ARGUMENTS> in L<openssl(1)>. (Optional) + +=item B<-signer> tsa_cert.pem + +The signer certificate of the TSA in PEM format. The TSA signing +certificate must have exactly one extended key usage assigned to it: +timeStamping. The extended key usage must also be critical, otherwise +the certificate is going to be refused. Overrides the B<signer_cert> +variable of the config file. (Optional) + +=item B<-inkey> file_or_id + +The signer private key of the TSA in PEM format. Overrides the +B<signer_key> config file option. (Optional) +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. + +=item B<-sha1|-sha224|-sha256|-sha384|-sha512> + +Signing digest to use. Overrides the B<signer_digest> config file +option. (Optional) + +=item B<-chain> certs_file.pem + +The collection of certificates in PEM format that will all +be included in the response in addition to the signer certificate if +the B<-cert> option was used for the request. This file is supposed to +contain the certificate chain for the signer certificate from its +issuer upwards. The B<-reply> command does not build a certificate +chain automatically. (Optional) + +=item B<-tspolicy> object_id + +The default policy to use for the response unless the client +explicitly requires a particular TSA policy. The OID can be specified +either in dotted notation or with its name. Overrides the +B<default_policy> config file option. (Optional) + +=item B<-in> response.tsr + +Specifies a previously created time stamp response or time stamp token +(if B<-token_in> is also specified) in DER format that will be written +to the output file. This option does not require a request, it is +useful e.g. when you need to examine the content of a response or +token or you want to extract the time stamp token from a response. If +the input is a token and the output is a time stamp response a default +'granted' status info is added to the token. (Optional) + +=item B<-token_in> + +This flag can be used together with the B<-in> option and indicates +that the input is a DER encoded time stamp token (ContentInfo) instead +of a time stamp response (TimeStampResp). (Optional) + +=item B<-out> response.tsr + +The response is written to this file. The format and content of the +file depends on other options (see B<-text>, B<-token_out>). The default is +stdout. (Optional) + +=item B<-token_out> + +The output is a time stamp token (ContentInfo) instead of time stamp +response (TimeStampResp). (Optional) + +=item B<-text> + +If this option is specified the output is human-readable text format +instead of DER. (Optional) + +=item B<-engine> id + +Specifying an engine (by its unique B<id> string) will cause B<ts> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. Default is builtin. (Optional) + +=back + +=head2 Time Stamp Response verification + +The B<-verify> command is for verifying if a time stamp response or time +stamp token is valid and matches a particular time stamp request or +data file. The B<-verify> command does not use the configuration file. + +=over 4 + +=item B<-data> file_to_hash + +The response or token must be verified against file_to_hash. The file +is hashed with the message digest algorithm specified in the token. +The B<-digest> and B<-queryfile> options must not be specified with this one. +(Optional) + +=item B<-digest> digest_bytes + +The response or token must be verified against the message digest specified +with this option. The number of bytes must match the message digest algorithm +specified in the token. The B<-data> and B<-queryfile> options must not be +specified with this one. (Optional) + +=item B<-queryfile> request.tsq + +The original time stamp request in DER format. The B<-data> and B<-digest> +options must not be specified with this one. (Optional) + +=item B<-in> response.tsr + +The time stamp response that needs to be verified in DER format. (Mandatory) + +=item B<-token_in> + +This flag can be used together with the B<-in> option and indicates +that the input is a DER encoded time stamp token (ContentInfo) instead +of a time stamp response (TimeStampResp). (Optional) + +=item B<-CApath> trusted_cert_path + +The name of the directory containing the trusted CA certificates of the +client. See the similar option of L<verify(1)> for additional +details. Either this option or B<-CAfile> must be specified. (Optional) + + +=item B<-CAfile> trusted_certs.pem + +The name of the file containing a set of trusted self-signed CA +certificates in PEM format. See the similar option of +L<verify(1)> for additional details. Either this option +or B<-CApath> must be specified. +(Optional) + +=item B<-untrusted> cert_file.pem + +Set of additional untrusted certificates in PEM format which may be +needed when building the certificate chain for the TSA's signing +certificate. This file must contain the TSA signing certificate and +all intermediate CA certificates unless the response includes them. +(Optional) + +=item I<verify options> + +The options B<-attime timestamp>, B<-check_ss_sig>, B<-crl_check>, +B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, +B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-no_alt_chains>, +B<-no_check_time>, B<-partial_chain>, B<-policy>, B<-policy_check>, +B<-policy_print>, B<-purpose>, B<-suiteB_128>, B<-suiteB_128_only>, +B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, B<-auth_level>, +B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>, +B<-verify_name>, and B<-x509_strict> can be used to control timestamp +verification. See L<verify(1)>. + +=back + +=head1 CONFIGURATION FILE OPTIONS + +The B<-query> and B<-reply> commands make use of a configuration file. +See L<config(5)> +for a general description of the syntax of the config file. The +B<-query> command uses only the symbolic OID names section +and it can work without it. However, the B<-reply> command needs the +config file for its operation. + +When there is a command line switch equivalent of a variable the +switch always overrides the settings in the config file. + +=over 4 + +=item B<tsa> section, B<default_tsa> + +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 overridden with the B<-section> command line switch. (Optional) + +=item B<oid_file> + +See L<ca(1)> for description. (Optional) + +=item B<oid_section> + +See L<ca(1)> for description. (Optional) + +=item B<RANDFILE> + +See L<ca(1)> for description. (Optional) + +=item B<serial> + +The name of the file containing the hexadecimal serial number of the +last time stamp response created. This number is incremented by 1 for +each response. If the file does not exist at the time of response +generation a new file is created with serial number 1. (Mandatory) + +=item B<crypto_device> + +Specifies the OpenSSL engine that will be set as the default for +all available algorithms. The default value is builtin, you can specify +any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM). +(Optional) + +=item B<signer_cert> + +TSA signing certificate in PEM format. The same as the B<-signer> +command line option. (Optional) + +=item B<certs> + +A file containing a set of PEM encoded certificates that need to be +included in the response. The same as the B<-chain> command line +option. (Optional) + +=item B<signer_key> + +The private key of the TSA in PEM format. The same as the B<-inkey> +command line option. (Optional) + +=item B<signer_digest> + +Signing digest to use. The same as the +B<-sha1|-sha224|-sha256|-sha384|-sha512> command line option. (Optional) + +=item B<default_policy> + +The default policy to use when the request does not mandate any +policy. The same as the B<-tspolicy> command line option. (Optional) + +=item B<other_policies> + +Comma separated list of policies that are also acceptable by the TSA +and used only if the request explicitly specifies one of them. (Optional) + +=item B<digests> + +The list of message digest algorithms that the TSA accepts. At least +one algorithm must be specified. (Mandatory) + +=item B<accuracy> + +The accuracy of the time source of the TSA in seconds, milliseconds +and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of +the components is missing zero is assumed for that field. (Optional) + +=item B<clock_precision_digits> + +Specifies the maximum number of digits, which represent the fraction of +seconds, that need to be included in the time field. The trailing zeroes +must be removed from the time, so there might actually be fewer digits, +or no fraction of seconds at all. Supported only on UNIX platforms. +The maximum value is 6, default is 0. +(Optional) + +=item B<ordering> + +If this option is yes the responses generated by this TSA can always +be ordered, even if the time difference between two responses is less +than the sum of their accuracies. Default is no. (Optional) + +=item B<tsa_name> + +Set this option to yes if the subject name of the TSA must be included in +the TSA name field of the response. Default is no. (Optional) + +=item B<ess_cert_id_chain> + +The SignedData objects created by the TSA always contain the +certificate identifier of the signing certificate in a signed +attribute (see RFC 2634, Enhanced Security Services). If this option +is set to yes and either the B<certs> variable or the B<-chain> option +is specified then the certificate identifiers of the chain will also +be included in the SigningCertificate signed attribute. If this +variable is set to no, only the signing certificate identifier is +included. Default is no. (Optional) + +=back + +=head1 EXAMPLES + +All the examples below presume that B<OPENSSL_CONF> is set to a proper +configuration file, e.g. the example configuration file +openssl/apps/openssl.cnf will do. + +=head2 Time Stamp Request + +To create a time stamp request for design1.txt with SHA-1 +without nonce and policy and no certificate is required in the response: + + openssl ts -query -data design1.txt -no_nonce \ + -out design1.tsq + +To create a similar time stamp request with specifying the message imprint +explicitly: + + openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ + -no_nonce -out design1.tsq + +To print the content of the previous request in human readable format: + + openssl ts -query -in design1.tsq -text + +To create a time stamp request which includes the MD-5 digest +of design2.txt, requests the signer certificate and nonce, +specifies a policy id (assuming the tsa_policy1 name is defined in the +OID section of the config file): + + openssl ts -query -data design2.txt -md5 \ + -tspolicy tsa_policy1 -cert -out design2.tsq + +=head2 Time Stamp Response + +Before generating a response a signing certificate must be created for +the TSA that contains the B<timeStamping> critical extended key usage extension +without any other key usage extensions. You can add the +'extendedKeyUsage = critical,timeStamping' line to the user certificate section +of the config file to generate a proper certificate. See L<req(1)>, +L<ca(1)>, L<x509(1)> for instructions. The examples +below assume that cacert.pem contains the certificate of the CA, +tsacert.pem is the signing certificate issued by cacert.pem and +tsakey.pem is the private key of the TSA. + +To create a time stamp response for a request: + + openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \ + -signer tsacert.pem -out design1.tsr + +If you want to use the settings in the config file you could just write: + + openssl ts -reply -queryfile design1.tsq -out design1.tsr + +To print a time stamp reply to stdout in human readable format: + + openssl ts -reply -in design1.tsr -text + +To create a time stamp token instead of time stamp response: + + openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out + +To print a time stamp token to stdout in human readable format: + + openssl ts -reply -in design1_token.der -token_in -text -token_out + +To extract the time stamp token from a response: + + openssl ts -reply -in design1.tsr -out design1_token.der -token_out + +To add 'granted' status info to a time stamp token thereby creating a +valid response: + + openssl ts -reply -in design1_token.der -token_in -out design1.tsr + +=head2 Time Stamp Verification + +To verify a time stamp reply against a request: + + openssl ts -verify -queryfile design1.tsq -in design1.tsr \ + -CAfile cacert.pem -untrusted tsacert.pem + +To verify a time stamp reply that includes the certificate chain: + + openssl ts -verify -queryfile design2.tsq -in design2.tsr \ + -CAfile cacert.pem + +To verify a time stamp token against the original data file: + openssl ts -verify -data design2.txt -in design2.tsr \ + -CAfile cacert.pem + +To verify a time stamp token against a message imprint: + openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \ + -in design2.tsr -CAfile cacert.pem + +You could also look at the 'test' directory for more examples. + +=head1 BUGS + +=for comment foreign manuals: procmail(1), perl(1) + +If you find any bugs or you have suggestions please write to +Zoltan Glozik <zglozik@opentsa.org>. Known issues: + +=over 2 + +=item * + +No support for time stamps over SMTP, though it is quite easy +to implement an automatic e-mail based TSA with L<procmail(1)> +and L<perl(1)>. HTTP server support is provided in the form of +a separate apache module. HTTP client support is provided by +L<tsget(1)>. Pure TCP/IP protocol is not supported. + +=item * + +The file containing the last serial number of the TSA is not +locked when being read or written. This is a problem if more than one +instance of L<openssl(1)> is trying to create a time stamp +response at the same time. This is not an issue when using the apache +server module, it does proper locking. + +=item * + +Look for the FIXME word in the source files. + +=item * + +The source code should really be reviewed by somebody else, too. + +=item * + +More testing is needed, I have done only some basic tests (see +test/testtsa). + +=back + +=head1 SEE ALSO + +L<tsget(1)>, L<openssl(1)>, L<req(1)>, +L<x509(1)>, L<ca(1)>, L<genrsa(1)>, +L<config(5)> + +=head1 COPYRIGHT + +Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/tsget.pod b/openssl-1.1.0h/doc/apps/tsget.pod new file mode 100644 index 0000000..f566f3a --- /dev/null +++ b/openssl-1.1.0h/doc/apps/tsget.pod @@ -0,0 +1,200 @@ +=pod + +=head1 NAME + +openssl-tsget, +tsget - Time Stamping HTTP/HTTPS client + +=head1 SYNOPSIS + +B<tsget> +B<-h> server_url +[B<-e> extension] +[B<-o> output] +[B<-v>] +[B<-d>] +[B<-k> private_key.pem] +[B<-p> key_password] +[B<-c> client_cert.pem] +[B<-C> CA_certs.pem] +[B<-P> CA_path] +[B<-r> file:file...] +[B<-g> EGD_socket] +[request]... + +=head1 DESCRIPTION + +The B<tsget> command can be used for sending a time stamp request, as +specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing +the time stamp response in a file. This tool cannot be used for creating the +requests and verifying responses, you can use the OpenSSL B<ts(1)> command to +do that. B<tsget> can send several requests to the server without closing +the TCP connection if more than one requests are specified on the command +line. + +The tool sends the following HTTP request for each time stamp request: + + POST url HTTP/1.1 + User-Agent: OpenTSA tsget.pl/<version> + Host: <host>:<port> + Pragma: no-cache + Content-Type: application/timestamp-query + Accept: application/timestamp-reply + Content-Length: length of body + + ...binary request specified by the user... + +B<tsget> expects a response of type application/timestamp-reply, which is +written to a file without any interpretation. + +=head1 OPTIONS + +=over 4 + +=item B<-h> server_url + +The URL of the HTTP/HTTPS server listening for time stamp requests. + +=item B<-e> extension + +If the B<-o> option is not given this argument specifies the extension of the +output files. The base name of the output file will be the same as those of +the input files. Default extension is '.tsr'. (Optional) + +=item B<-o> output + +This option can be specified only when just one request is sent to the +server. The time stamp response will be written to the given output file. '-' +means standard output. In case of multiple time stamp requests or the absence +of this argument the names of the output files will be derived from the names +of the input files and the default or specified extension argument. (Optional) + +=item B<-v> + +The name of the currently processed request is printed on standard +error. (Optional) + +=item B<-d> + +Switches on verbose mode for the underlying B<curl> library. You can see +detailed debug messages for the connection. (Optional) + +=item B<-k> private_key.pem + +(HTTPS) In case of certificate-based client authentication over HTTPS +<private_key.pem> must contain the private key of the user. The private key +file can optionally be protected by a passphrase. The B<-c> option must also +be specified. (Optional) + +=item B<-p> key_password + +(HTTPS) Specifies the passphrase for the private key specified by the B<-k> +argument. If this option is omitted and the key is passphrase protected B<tsget> +will ask for it. (Optional) + +=item B<-c> client_cert.pem + +(HTTPS) In case of certificate-based client authentication over HTTPS +<client_cert.pem> must contain the X.509 certificate of the user. The B<-k> +option must also be specified. If this option is not specified no +certificate-based client authentication will take place. (Optional) + +=item B<-C> CA_certs.pem + +(HTTPS) The trusted CA certificate store. The certificate chain of the peer's +certificate must include one of the CA certificates specified in this file. +Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional) + +=item B<-P> CA_path + +(HTTPS) The path containing the trusted CA certificates to verify the peer's +certificate. The directory must be prepared with the B<c_rehash> +OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of +HTTPS. (Optional) + +=item B<-rand> file:file... + +The files containing random data for seeding the random number +generator. Multiple files can be specified, the separator is B<;> for +MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional) + +=item B<-g> EGD_socket + +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 specified only one request will be sent to the server and it will be +read from the standard input. (Optional) + +=back + +=head1 ENVIRONMENT VARIABLES + +The B<TSGET> environment variable can optionally contain default +arguments. The content of this variable is added to the list of command line +arguments. + +=head1 EXAMPLES + +The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid +time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests +and at port 8443 for HTTPS requests, the TSA service is available at the /tsa +absolute path. + +Get a time stamp response for file1.tsq over HTTP, output is written to +file1.tsr: + + tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq + +Get a time stamp response for file1.tsq and file2.tsq over HTTP showing +progress, output is written to file1.reply and file2.reply respectively: + + tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \ + file1.tsq file2.tsq + +Create a time stamp request, write it to file3.tsq, send it to the server and +write the response to file3.tsr: + + openssl ts -query -data file3.txt -cert | tee file3.tsq \ + | tsget -h http://tsa.opentsa.org:8080/tsa \ + -o file3.tsr + +Get a time stamp response for file1.tsq over HTTPS without client +authentication: + + tsget -h https://tsa.opentsa.org:8443/tsa \ + -C cacerts.pem file1.tsq + +Get a time stamp response for file1.tsq over HTTPS with certificate-based +client authentication (it will ask for the passphrase if client_key.pem is +protected): + + tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ + -k client_key.pem -c client_cert.pem file1.tsq + +You can shorten the previous command line if you make use of the B<TSGET> +environment variable. The following commands do the same as the previous +example: + + TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \ + -k client_key.pem -c client_cert.pem' + export TSGET + tsget file1.tsq + +=head1 SEE ALSO + +L<openssl(1)>, L<ts(1)>, L<curl(1)>, +B<RFC 3161> + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/verify.pod b/openssl-1.1.0h/doc/apps/verify.pod new file mode 100644 index 0000000..38fa346 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/verify.pod @@ -0,0 +1,725 @@ +=pod + +=head1 NAME + +openssl-verify, +verify - Utility to verify certificates + +=head1 SYNOPSIS + +B<openssl> B<verify> +[B<-help>] +[B<-CAfile file>] +[B<-CApath directory>] +[B<-no-CAfile>] +[B<-no-CApath>] +[B<-allow_proxy_certs>] +[B<-attime timestamp>] +[B<-check_ss_sig>] +[B<-CRLfile file>] +[B<-crl_download>] +[B<-crl_check>] +[B<-crl_check_all>] +[B<-engine id>] +[B<-explicit_policy>] +[B<-extended_crl>] +[B<-ignore_critical>] +[B<-inhibit_any>] +[B<-inhibit_map>] +[B<-no_check_time>] +[B<-partial_chain>] +[B<-policy arg>] +[B<-policy_check>] +[B<-policy_print>] +[B<-purpose purpose>] +[B<-suiteB_128>] +[B<-suiteB_128_only>] +[B<-suiteB_192>] +[B<-trusted_first>] +[B<-no_alt_chains>] +[B<-untrusted file>] +[B<-trusted file>] +[B<-use_deltas>] +[B<-verbose>] +[B<-auth_level level>] +[B<-verify_depth num>] +[B<-verify_email email>] +[B<-verify_hostname hostname>] +[B<-verify_ip ip>] +[B<-verify_name name>] +[B<-x509_strict>] +[B<-show_chain>] +[B<->] +[certificates] + +=head1 DESCRIPTION + +The B<verify> command verifies certificate chains. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-CAfile file> + +A B<file> of trusted certificates. +The file should contain one or more certificates in PEM format. + +=item B<-CApath directory> + +A directory of trusted certificates. The certificates should have names +of the form: hash.0 or have symbolic links to them of this +form ("hash" is the hashed certificate subject name: see the B<-hash> option +of the B<x509> utility). Under Unix the B<c_rehash> script will automatically +create symbolic links to a directory of certificates. + +=item B<-no-CAfile> + +Do not load the trusted CA certificates from the default file location + +=item B<-no-CApath> + +Do not load the trusted CA certificates from the default directory location + +=item B<-allow_proxy_certs> + +Allow the verification of proxy certificates + +=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<-check_ss_sig> + +Verify the signature on the self-signed root CA. This is disabled by default +because it doesn't add any security. + +=item B<-CRLfile file> + +The B<file> should contain one or more CRLs in PEM format. +This option can be specified more than once to include CRLs from multiple +B<files>. + +=item B<-crl_download> + +Attempt to download CRL information for this certificate. + +=item B<-crl_check> + +Checks end entity certificate validity by attempting to look up a valid CRL. +If a valid CRL cannot be found an error occurs. + +=item B<-crl_check_all> + +Checks the validity of B<all> certificates in the chain by attempting +to look up valid CRLs. + +=item B<-engine id> + +Specifying an engine B<id> will cause L<verify(1)> to attempt to load the +specified engine. +The engine will then be set as the default for all its supported algorithms. +If you want to load certificates or CRLs that require engine support via any of +the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option +must be specified before those options. + +=item B<-explicit_policy> + +Set policy variable require-explicit-policy (see RFC5280). + +=item B<-extended_crl> + +Enable extended CRL features such as indirect CRLs and alternate CRL +signing keys. + +=item B<-ignore_critical> + +Normally if an unhandled critical extension is present which is not +supported by OpenSSL the certificate is rejected (as required by RFC5280). +If this option is set critical extensions are ignored. + +=item B<-inhibit_any> + +Set policy variable inhibit-any-policy (see RFC5280). + +=item B<-inhibit_map> + +Set policy variable inhibit-policy-mapping (see RFC5280). + +=item B<-no_check_time> + +This option suppresses checking the validity period of certificates and CRLs +against the current time. If option B<-attime timestamp> is used to specify +a verification time, the check is not suppressed. + +=item B<-partial_chain> + +Allow verification to succeed even if a I<complete> chain cannot be built to a +self-signed trust-anchor, provided it is possible to construct a chain to a +trusted certificate that might not be self-signed. + +=item B<-policy arg> + +Enable policy processing and add B<arg> to the user-initial-policy-set (see +RFC5280). The policy B<arg> can be an object name an OID in numeric form. +This argument can appear more than once. + +=item B<-policy_check> + +Enables certificate policy processing. + +=item B<-policy_print> + +Print out diagnostics related to policy processing. + +=item B<-purpose purpose> + +The intended use for the certificate. If this option is not specified, +B<verify> will not consider certificate purpose during chain verification. +Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>, +B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more +information. + +=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192> + +enable the Suite B mode operation at 128 bit Level of Security, 128 bit or +192 bit, or only 192 bit Level of Security respectively. +See RFC6460 for details. In particular the supported signature algorithms are +reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves +P-256 and P-384. + +=item B<-trusted_first> + +When constructing the certificate chain, use the trusted certificates specified +via B<-CAfile>, B<-CApath> or B<-trusted> before any certificates specified via +B<-untrusted>. +This can be useful in environments with Bridge or Cross-Certified CAs. +As of OpenSSL 1.1.0 this option is on by default and cannot be disabled. + +=item B<-no_alt_chains> + +By default, unless B<-trusted_first> is specified, when building a certificate +chain, if the first certificate chain found is not trusted, then OpenSSL will +attempt to replace untrusted issuer certificates with certificates from the +trust store to see if an alternative chain can be found that is trusted. +As of OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no +effect. + +=item B<-untrusted file> + +A B<file> of additional untrusted certificates (intermediate issuer CAs) used +to construct a certificate chain from the subject certificate to a trust-anchor. +The B<file> should contain one or more certificates in PEM format. +This option can be specified more than once to include untrusted certificates +from multiple B<files>. + +=item B<-trusted file> + +A B<file> of trusted certificates, which must be self-signed, unless the +B<-partial_chain> option is specified. +The B<file> contains one or more certificates in PEM format. +With this option, no additional (e.g., default) certificate lists are +consulted. +That is, the only trust-anchors are those listed in B<file>. +This option can be specified more than once to include trusted certificates +from multiple B<files>. +This option implies the B<-no-CAfile> and B<-no-CApath> options. +This option cannot be used in combination with either of the B<-CAfile> or +B<-CApath> options. + +=item B<-use_deltas> + +Enable support for delta CRLs. + +=item B<-verbose> + +Print extra information about the operations being performed. + +=item B<-auth_level level> + +Set the certificate chain authentication security level to B<level>. +The authentication security level determines the acceptable signature and +public key strength when verifying certificate chains. +For a certificate chain to validate, the public keys of all the certificates +must meet the specified security B<level>. +The signature algorithm security level is enforced for all the certificates in +the chain except for the chain's I<trust anchor>, which is either directly +trusted or validated by means other than its signature. +See L<SSL_CTX_set_security_level(3)> for the definitions of the available +levels. +The default security level is -1, or "not set". +At security level 0 or lower all algorithms are acceptable. +Security level 1 requires at least 80-bit-equivalent security and is broadly +interoperable, though it will, for example, reject MD5 signatures or RSA keys +shorter than 1024 bits. + +=item B<-verify_depth num> + +Limit the certificate chain to B<num> intermediate CA certificates. +A maximal depth chain can have up to B<num+2> certificates, since neither the +end-entity certificate nor the trust-anchor certificate count against the +B<-verify_depth> limit. + +=item B<-verify_email email> + +Verify if the B<email> matches the email address in Subject Alternative Name or +the email in the subject Distinguished Name. + +=item B<-verify_hostname hostname> + +Verify if the B<hostname> matches DNS name in Subject Alternative Name or +Common Name in the subject certificate. + +=item B<-verify_ip ip> + +Verify if the B<ip> matches the IP address in Subject Alternative Name of +the subject certificate. + +=item B<-verify_name name> + +Use default verification policies like trust model and required certificate +policies identified by B<name>. +The trust model determines which auxiliary trust or reject OIDs are applicable +to verifying the given certificate chain. +See the B<-addtrust> and B<-addreject> options of the L<x509(1)> command-line +utility. +Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>, +B<ssl_client>, B<ssl_server>. +These mimics the combinations of purpose and trust settings used in SSL, CMS +and S/MIME. +As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not +specified, so the B<-verify_name> options are functionally equivalent to the +corresponding B<-purpose> settings. + +=item B<-x509_strict> + +For strict X.509 compliance, disable non-compliant workarounds for broken +certificates. + +=item B<-show_chain> + +Display information about the certificate chain that has been built (if +successful). Certificates in the chain that came from the untrusted list will be +flagged as "untrusted". + +=item B<-> + +Indicates the last option. All arguments following this are assumed to be +certificate files. This is useful if the first certificate filename begins +with a B<->. + +=item B<certificates> + +One or more certificates to verify. If no certificates are given, B<verify> +will attempt to read a certificate from standard input. Certificates must be +in PEM format. + +=back + +=head1 VERIFY OPERATION + +The B<verify> program uses the same functions as the internal SSL and S/MIME +verification, therefore this description applies to these verify operations +too. + +There is one crucial difference between the verify operations performed +by the B<verify> program: wherever possible an attempt is made to continue +after an error whereas normally the verify operation would halt on the +first error. This allows all the problems with a certificate chain to be +determined. + +The verify operation consists of a number of separate steps. + +Firstly a certificate chain is built up starting from the supplied certificate +and ending in the root CA. +It is an error if the whole chain cannot be built up. +The chain is built up by looking up the issuers certificate of the current +certificate. +If a certificate is found which is its own issuer it is assumed to be the root +CA. + +The process of 'looking up the issuers certificate' itself involves a number of +steps. +After all certificates whose subject name matches the issuer name of the current +certificate are subject to further tests. +The relevant authority key identifier components of the current certificate (if +present) must match the subject key identifier (if present) and issuer and +serial number of the candidate issuer, in addition the keyUsage extension of +the candidate issuer (if present) must permit certificate signing. + +The lookup first looks in the list of untrusted certificates and if no match +is found the remaining lookups are from the trusted certificates. The root CA +is always looked up in the trusted certificate list: if the certificate to +verify is a root certificate then an exact match must be found in the trusted +list. + +The second operation is to check every untrusted certificate's extensions for +consistency with the supplied purpose. If the B<-purpose> option is not included +then no checks are done. The supplied or "leaf" certificate must have extensions +compatible with the supplied purpose and all other certificates must also be valid +CA certificates. The precise extensions required are described in more detail in +the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility. + +The third operation is to check the trust settings on the root CA. The root CA +should be trusted for the supplied purpose. +For compatibility with previous versions of OpenSSL, a certificate with no +trust settings is considered to be valid for all purposes. + +The final operation is to check the validity of the certificate chain. The validity +period is checked against the current system time and the notBefore and notAfter +dates in the certificate. The certificate signatures are also checked at this +point. + +If all operations complete successfully then certificate is considered valid. If +any operation fails then the certificate is not valid. + +=head1 DIAGNOSTICS + +When a verify operation fails the output messages can be somewhat cryptic. The +general form of the error message is: + + server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) + error 24 at 1 depth lookup:invalid CA certificate + +The first line contains the name of the certificate being verified followed by +the subject name of the certificate. The second line contains the error number +and the depth. The depth is number of the certificate being verified when a +problem was detected starting with zero for the certificate being verified itself +then 1 for the CA that signed the certificate and so on. Finally a text version +of the error number is presented. + +A partial list of the error codes and messages is shown below, this also +includes the name of the error code as defined in the header file x509_vfy.h +Some of the error codes are defined but never returned: these are described +as "unused". + +=over 4 + +=item B<X509_V_OK> + +The operation was successful. + +=item B<X509_V_ERR_UNSPECIFIED> + +Unspecified error; should not happen. + +=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> + +The issuer certificate of a looked up certificate could not be found. This +normally means the list of trusted certificates is not complete. + +=item B<X509_V_ERR_UNABLE_TO_GET_CRL> + +The CRL of a certificate could not be found. + +=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE> + +The certificate signature could not be decrypted. This means that the actual signature value +could not be determined rather than it not matching the expected value, this is only +meaningful for RSA keys. + +=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE> + +The CRL signature could not be decrypted: this means that the actual signature value +could not be determined rather than it not matching the expected value. Unused. + +=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY> + +The public key in the certificate SubjectPublicKeyInfo could not be read. + +=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE> + +The signature of the certificate is invalid. + +=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE> + +The signature of the certificate is invalid. + +=item B<X509_V_ERR_CERT_NOT_YET_VALID> + +The certificate is not yet valid: the notBefore date is after the current time. + +=item B<X509_V_ERR_CERT_HAS_EXPIRED> + +The certificate has expired: that is the notAfter date is before the current time. + +=item B<X509_V_ERR_CRL_NOT_YET_VALID> + +The CRL is not yet valid. + +=item B<X509_V_ERR_CRL_HAS_EXPIRED> + +The CRL has expired. + +=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD> + +The certificate notBefore field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD> + +The certificate notAfter field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD> + +The CRL lastUpdate field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD> + +The CRL nextUpdate field contains an invalid time. + +=item B<X509_V_ERR_OUT_OF_MEM> + +An error occurred trying to allocate memory. This should never happen. + +=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT> + +The passed certificate is self-signed and the same certificate cannot be found in the list of +trusted certificates. + +=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN> + +The certificate chain could be built up using the untrusted certificates but the root could not +be found locally. + +=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> + +The issuer certificate could not be found: this occurs if the issuer +certificate of an untrusted certificate cannot be found. + +=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE> + +No signatures could be verified because the chain contains only one certificate and it is not +self signed. + +=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG> + +The certificate chain length is greater than the supplied maximum depth. Unused. + +=item B<X509_V_ERR_CERT_REVOKED> + +The certificate has been revoked. + +=item B<X509_V_ERR_INVALID_CA> + +A CA certificate is invalid. Either it is not a CA or its extensions are not consistent +with the supplied purpose. + +=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED> + +The basicConstraints pathlength parameter has been exceeded. + +=item B<X509_V_ERR_INVALID_PURPOSE> + +The supplied certificate cannot be used for the specified purpose. + +=item B<X509_V_ERR_CERT_UNTRUSTED> + +the root CA is not marked as trusted for the specified purpose. + +=item B<X509_V_ERR_CERT_REJECTED> + +The root CA is marked to reject the specified purpose. + +=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH> + +not used as of OpenSSL 1.1.0 as a result of the deprecation of the +B<-issuer_checks> option. + +=item B<X509_V_ERR_AKID_SKID_MISMATCH> + +Not used as of OpenSSL 1.1.0 as a result of the deprecation of the +B<-issuer_checks> option. + +=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH> + +Not used as of OpenSSL 1.1.0 as a result of the deprecation of the +B<-issuer_checks> option. + +=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN> + +Not used as of OpenSSL 1.1.0 as a result of the deprecation of the +B<-issuer_checks> option. + +=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER> + +Unable to get CRL issuer certificate. + +=item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION> + +Unhandled critical extension. + +=item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN> + +Key usage does not include CRL signing. + +=item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION> + +Unhandled critical CRL extension. + +=item B<X509_V_ERR_INVALID_NON_CA> + +Invalid non-CA certificate has CA markings. + +=item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED> + +Proxy path length constraint exceeded. + +=item B<X509_V_ERR_PROXY_SUBJECT_INVALID> + +Proxy certificate subject is invalid. It MUST be the same as the issuer +with a single CN component added. + +=item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE> + +Key usage does not include digital signature. + +=item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED> + +Proxy certificates not allowed, please use B<-allow_proxy_certs>. + +=item B<X509_V_ERR_INVALID_EXTENSION> + +Invalid or inconsistent certificate extension. + +=item B<X509_V_ERR_INVALID_POLICY_EXTENSION> + +Invalid or inconsistent certificate policy extension. + +=item B<X509_V_ERR_NO_EXPLICIT_POLICY> + +No explicit policy. + +=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE> + +Different CRL scope. + +=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE> + +Unsupported extension feature. + +=item B<X509_V_ERR_UNNESTED_RESOURCE> + +RFC 3779 resource not subset of parent's resources. + +=item B<X509_V_ERR_PERMITTED_VIOLATION> + +Permitted subtree violation. + +=item B<X509_V_ERR_EXCLUDED_VIOLATION> + +Excluded subtree violation. + +=item B<X509_V_ERR_SUBTREE_MINMAX> + +Name constraints minimum and maximum not supported. + +=item B<X509_V_ERR_APPLICATION_VERIFICATION> + +Application verification failure. Unused. + +=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE> + +Unsupported name constraint type. + +=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX> + +Unsupported or invalid name constraint syntax. + +=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX> + +Unsupported or invalid name syntax. + +=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR> + +CRL path validation error. + +=item B<X509_V_ERR_PATH_LOOP> + +Path loop. + +=item B<X509_V_ERR_SUITE_B_INVALID_VERSION> + +Suite B: certificate version invalid. + +=item B<X509_V_ERR_SUITE_B_INVALID_ALGORITHM> + +Suite B: invalid public key algorithm. + +=item B<X509_V_ERR_SUITE_B_INVALID_CURVE> + +Suite B: invalid ECC curve. + +=item B<X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM> + +Suite B: invalid signature algorithm. + +=item B<X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED> + +Suite B: curve not allowed for this LOS. + +=item B<X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256> + +Suite B: cannot sign P-384 with P-256. + +=item B<X509_V_ERR_HOSTNAME_MISMATCH> + +Hostname mismatch. + +=item B<X509_V_ERR_EMAIL_MISMATCH> + +Email address mismatch. + +=item B<X509_V_ERR_IP_ADDRESS_MISMATCH> + +IP address mismatch. + +=item B<X509_V_ERR_DANE_NO_MATCH> + +DANE TLSA authentication is enabled, but no TLSA records matched the +certificate chain. +This error is only possible in L<s_client(1)>. + +=back + +=head1 BUGS + +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 +the certificates in the file will be recognised. + +Previous versions of OpenSSL assume certificates with matching subject name are identical and +mishandled them. + +Previous versions of this documentation swapped the meaning of the +B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and +B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. + +=head1 SEE ALSO + +L<x509(1)> + +=head1 HISTORY + +The B<-show_chain> option was first added to OpenSSL 1.1.0. + +The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and +is silently ignored. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/version.pod b/openssl-1.1.0h/doc/apps/version.pod new file mode 100644 index 0000000..305a1b7 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/version.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +openssl-version, +version - print OpenSSL version information + +=head1 SYNOPSIS + +B<openssl version> +[B<-help>] +[B<-a>] +[B<-v>] +[B<-b>] +[B<-o>] +[B<-f>] +[B<-p>] +[B<-d>] +[B<-e>] + +=head1 DESCRIPTION + +This command is used to print out version information about OpenSSL. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-a> + +all information, this is the same as setting all the other flags. + +=item B<-v> + +the current OpenSSL version. + +=item B<-b> + +the date the current version of OpenSSL was built. + +=item B<-o> + +option information: various options set when the library was built. + +=item B<-f> + +compilation flags. + +=item B<-p> + +platform setting. + +=item B<-d> + +OPENSSLDIR setting. + +=item B<-e> + +ENGINESDIR setting. + +=back + +=head1 NOTES + +The output of B<openssl version -a> would typically be used when sending +in a bug report. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/x509.pod b/openssl-1.1.0h/doc/apps/x509.pod new file mode 100644 index 0000000..f2dcef2 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/x509.pod @@ -0,0 +1,898 @@ +=pod + +=head1 NAME + +openssl-x509, +x509 - Certificate display and signing utility + +=head1 SYNOPSIS + +B<openssl> B<x509> +[B<-help>] +[B<-inform DER|PEM|NET>] +[B<-outform DER|PEM|NET>] +[B<-keyform DER|PEM>] +[B<-CAform DER|PEM>] +[B<-CAkeyform DER|PEM>] +[B<-in filename>] +[B<-out filename>] +[B<-serial>] +[B<-hash>] +[B<-subject_hash>] +[B<-issuer_hash>] +[B<-ocspid>] +[B<-subject>] +[B<-issuer>] +[B<-nameopt option>] +[B<-email>] +[B<-ocsp_uri>] +[B<-startdate>] +[B<-enddate>] +[B<-purpose>] +[B<-dates>] +[B<-checkend num>] +[B<-modulus>] +[B<-pubkey>] +[B<-fingerprint>] +[B<-alias>] +[B<-noout>] +[B<-trustout>] +[B<-clrtrust>] +[B<-clrreject>] +[B<-addtrust arg>] +[B<-addreject arg>] +[B<-setalias arg>] +[B<-days arg>] +[B<-set_serial n>] +[B<-signkey filename>] +[B<-passin arg>] +[B<-x509toreq>] +[B<-req>] +[B<-CA filename>] +[B<-CAkey filename>] +[B<-CAcreateserial>] +[B<-CAserial filename>] +[B<-force_pubkey key>] +[B<-text>] +[B<-certopt option>] +[B<-C>] +[B<-[digest]>] +[B<-clrext>] +[B<-extfile filename>] +[B<-extensions section>] +[B<-engine id>] + +=head1 DESCRIPTION + +The B<x509> command is a multi purpose certificate utility. It can be +used to display certificate information, convert certificates to +various forms, sign certificate requests like a "mini CA" or edit +certificate trust settings. + +Since there are a large number of options they will split up into +various sections. + +=head1 OPTIONS + +=head2 Input, Output, and General Purpose Options + +=over 4 + +=item B<-help> + +Print out a usage message. + +=item B<-inform DER|PEM|NET> + +This specifies the input format normally the command will expect an X509 +certificate but this can change if other options such as B<-req> are +present. The DER format is the DER encoding of the certificate and PEM +is the base64 encoding of the DER encoding with header and footer lines +added. The NET option is an obscure Netscape server format that is now +obsolete. + +=item B<-outform DER|PEM|NET> + +This specifies the output format, the options have the same meaning as the +B<-inform> option. + +=item B<-in filename> + +This specifies the input filename to read a certificate from or standard input +if this option is not specified. + +=item B<-out filename> + +This specifies the output filename to write to or standard output by +default. + +=item B<-[digest]> + +the digest to use. +This affects any signing or display option that uses a message +digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. +Any digest supported by the OpenSSL B<dgst> command can be used. +If not specified then SHA1 is used with B<-fingerprint> or +the default digest for the signing algorithm is used, typically SHA256. + +=item B<-engine id> + +specifying an engine (by its unique B<id> string) will cause B<x509> +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. + +=back + +=head2 Display Options + +Note: the B<-alias> and B<-purpose> options are also display options +but are described in the B<TRUST SETTINGS> section. + +=over 4 + +=item B<-text> + +prints out the certificate in text form. Full details are output including the +public key, signature algorithms, issuer and subject names, serial number +any extensions present and any trust settings. + +=item B<-certopt option> + +customise the output format used with B<-text>. The B<option> argument can be +a single option or multiple options separated by commas. The B<-certopt> switch +may be also be used more than once to set multiple options. See the B<TEXT OPTIONS> +section for more information. + +=item B<-noout> + +this option prevents output of the encoded version of the request. + +=item B<-pubkey> + +outputs the certificate's SubjectPublicKeyInfo block in PEM format. + +=item B<-modulus> + +this option prints out the value of the modulus of the public key +contained in the certificate. + +=item B<-serial> + +outputs the certificate serial number. + +=item B<-subject_hash> + +outputs the "hash" of the certificate subject name. This is used in OpenSSL to +form an index to allow certificates in a directory to be looked up by subject +name. + +=item B<-issuer_hash> + +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. + +=item B<-subject_hash_old> + +outputs the "hash" of the certificate subject name using the older algorithm +as used by OpenSSL versions before 1.0.0. + +=item B<-issuer_hash_old> + +outputs the "hash" of the certificate issuer name using the older algorithm +as used by OpenSSL versions before 1.0.0. + +=item B<-subject> + +outputs the subject name. + +=item B<-issuer> + +outputs the issuer name. + +=item B<-nameopt option> + +option which determines how the subject or issuer names are displayed. The +B<option> argument can be a single option or multiple options separated by +commas. Alternatively the B<-nameopt> switch may be used more than once to +set multiple options. See the B<NAME OPTIONS> section for more information. + +=item B<-email> + +outputs the email address(es) if any. + +=item B<-ocsp_uri> + +outputs the OCSP responder address(es) if any. + +=item B<-startdate> + +prints out the start date of the certificate, that is the notBefore date. + +=item B<-enddate> + +prints out the expiry date of the certificate, that is the notAfter date. + +=item B<-dates> + +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> + +Calculates and outputs the digest of the DER encoded version of the entire +certificate (see digest options). +This is commonly called a "fingerprint". Because of the nature of message +digests, the fingerprint of a certificate is unique to that certificate and +two certificates with the same fingerprint can be considered to be the same. + +=item B<-C> + +this outputs the certificate in the form of a C source file. + +=back + +=head2 Trust Settings + +A B<trusted certificate> is an ordinary certificate which has several +additional pieces of information attached to it such as the permitted +and prohibited uses of the certificate and an "alias". + +Normally when a certificate is being verified at least one certificate +must be "trusted". By default a trusted certificate must be stored +locally and must be a root CA: any certificate chain ending in this CA +is then usable for any purpose. + +Trust settings currently are only used with a root CA. They allow a finer +control over the purposes the root CA can be used for. For example a CA +may be trusted for SSL client but not SSL server use. + +See the description of the B<verify> utility for more information on the +meaning of trust settings. + +Future versions of OpenSSL will recognize trust settings on any +certificate: not just root CAs. + + +=over 4 + +=item B<-trustout> + +this causes B<x509> to output a B<trusted> certificate. An ordinary +or trusted certificate can be input but by default an ordinary +certificate is output and any trust settings are discarded. With the +B<-trustout> option a trusted certificate is output. A trusted +certificate is automatically output if any trust settings are modified. + +=item B<-setalias arg> + +sets the alias of the certificate. This will allow the certificate +to be referred to using a nickname for example "Steve's Certificate". + +=item B<-alias> + +outputs the certificate alias, if any. + +=item B<-clrtrust> + +clears all the permitted or trusted uses of the certificate. + +=item B<-clrreject> + +clears all the prohibited or rejected uses of the certificate. + +=item B<-addtrust arg> + +adds a trusted certificate use. +Any object name can be used here but currently only B<clientAuth> (SSL client +use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and +B<anyExtendedKeyUsage> are used. +As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or +enables all purposes when trusted. +Other OpenSSL applications may define additional uses. + +=item B<-addreject arg> + +adds a prohibited use. It accepts the same values as the B<-addtrust> +option. + +=item B<-purpose> + +this option performs tests on the certificate extensions and outputs +the results. For a more complete description see the B<CERTIFICATE +EXTENSIONS> section. + +=back + +=head2 Signing Options + +The B<x509> utility can be used to sign certificates and requests: it +can thus behave like a "mini CA". + +=over 4 + +=item B<-signkey filename> + +this option causes the input file to be self signed using the supplied +private key. + +If the input file is a certificate it sets the issuer name to the +subject name (i.e. makes it self signed) changes the public key to the +supplied value and changes the start and end dates. The start date is +set to the current time and the end date is set to a value determined +by the B<-days> option. Any certificate extensions are retained unless +the B<-clrext> option is supplied; this includes, for example, any existing +key identifier extensions. + +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)>. + +=item B<-clrext> + +delete any extensions from a certificate. This option is used when a +certificate is being created from another certificate (for example with +the B<-signkey> or the B<-CA> options). Normally all extensions are +retained. + +=item B<-keyform PEM|DER> + +specifies the format (DER or PEM) of the private key file used in the +B<-signkey> option. + +=item B<-days arg> + +specifies the number of days to make a certificate valid for. The default +is 30 days. + +=item B<-x509toreq> + +converts a certificate into a certificate request. The B<-signkey> option +is used to pass the required private key. + +=item B<-req> + +by default a certificate is expected on input. With this option a +certificate request is expected instead. + +=item B<-set_serial n> + +specifies the serial number to use. This option can be used with either +the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA> +option the serial number file (as specified by the B<-CAserial> or +B<-CAcreateserial> options) is not used. + +The serial number can be decimal or hex (if preceded by B<0x>). + +=item B<-CA filename> + +specifies the CA certificate to be used for signing. When this option is +present B<x509> behaves like a "mini CA". The input file is signed by this +CA using this option: that is its issuer name is set to the subject name +of the CA and it is digitally signed using the CAs private key. + +This option is normally combined with the B<-req> option. Without the +B<-req> option the input is a certificate which must be self signed. + +=item B<-CAkey filename> + +sets the CA private key to sign a certificate with. If this option is +not specified then it is assumed that the CA private key is present in +the CA certificate file. + +=item B<-CAserial filename> + +sets the CA serial number file to use. + +When the B<-CA> option is used to sign a certificate it uses a serial +number specified in a file. This file consist of one line containing +an even number of hex digits with the serial number to use. After each +use the serial number is incremented and written out to the file again. + +The default filename consists of the CA certificate file base name with +".srl" appended. For example if the CA certificate file is called +"mycacert.pem" it expects to find a serial number file called "mycacert.srl". + +=item B<-CAcreateserial> + +with this option the CA serial number file is created if it does not exist: +it will contain the serial number "02" and the certificate being signed will +have the 1 as its serial number. If the B<-CA> option is specified +and the serial number file does not exist a random number is generated; +this is the recommended practice. + +=item B<-extfile filename> + +file containing certificate extensions to use. If not specified then +no extensions are added to the certificate. + +=item B<-extensions section> + +the section to add certificate extensions from. If this option is not +specified then the extensions should either be contained in the unnamed +(default) section or the default section should contain a variable called +"extensions" which contains the section to use. See the +L<x509v3_config(5)> manual page for details of the +extension section format. + +=item B<-force_pubkey key> + +when a certificate is created set its public key to B<key> instead of the +key in the certificate or certificate request. This option is useful for +creating certificates where the algorithm can't normally sign requests, for +example DH. + +The format or B<key> can be specified using the B<-keyform> option. + +=back + +=head2 Name Options + +The B<nameopt> command line switch determines how the subject and issuer +names are displayed. If no B<nameopt> switch is present the default "oneline" +format is used which is compatible with previous versions of OpenSSL. +Each option is described in detail below, all options can be preceded by +a B<-> to turn the option off. Only the first four will normally be used. + +=over 4 + +=item B<compat> + +use the old format. + +=item B<RFC2253> + +displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>, +B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>, +B<sep_comma_plus>, B<dn_rev> and B<sname>. + +=item B<oneline> + +a oneline format which is more readable than RFC2253. It is equivalent to +specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>, +B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname> +options. This is the I<default> of no name options are given explicitly. + +=item B<multiline> + +a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, +B<space_eq>, B<lname> and B<align>. + +=item B<esc_2253> + +escape the "special" characters required by RFC2253 in a field. That is +B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string +and a space character at the beginning or end of a string. + +=item B<esc_2254> + +escape the "special" characters required by RFC2254 in a field. That is +the B<NUL> character as well as and B<()*>. + +=item B<esc_ctrl> + +escape control characters. That is those with ASCII values less than +0x20 (space) and the delete (0x7f) character. They are escaped using the +RFC2253 \XX notation (where XX are two hex digits representing the +character value). + +=item B<esc_msb> + +escape characters with the MSB set, that is with ASCII values larger than +127. + +=item B<use_quote> + +escapes some characters by surrounding the whole string with B<"> characters, +without the option all escaping is done with the B<\> character. + +=item B<utf8> + +convert all strings to UTF8 format first. This is required by RFC2253. If +you are lucky enough to have a UTF8 compatible terminal then the use +of this option (and B<not> setting B<esc_msb>) may result in the correct +display of multibyte (international) characters. Is this option is not +present then multibyte characters larger than 0xff will be represented +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<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 +represents each character. This is useful for diagnostic purposes but +will result in rather odd looking output. + +=item B<show_type> + +show the type of the ASN1 character string. The type precedes the +field contents. For example "BMPSTRING: Hello World". + +=item B<dump_der> + +when this option is set any fields that need to be hexdumped will +be dumped using the DER encoding of the field. Otherwise just the +content octets will be displayed. Both options use the RFC2253 +B<#XXXX...> format. + +=item B<dump_nostr> + +dump non character string types (for example OCTET STRING) if this +option is not set then non character string types will be displayed +as though each content octet represents a single character. + +=item B<dump_all> + +dump all fields. This option when used with B<dump_der> allows the +DER encoding of the structure to be unambiguously determined. + +=item B<dump_unknown> + +dump any field whose OID is not recognised by OpenSSL. + +=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>, +B<sep_multiline> + +these options determine the field separators. The first character is +between RDNs and the second between multiple AVAs (multiple AVAs are +very rare and their use is discouraged). The options ending in +"space" additionally place a space after the separator to make it +more readable. The B<sep_multiline> uses a linefeed character for +the RDN separator and a spaced B<+> for the AVA separator. It also +indents the fields by four characters. If no field separator is specified +then B<sep_comma_plus_space> is used by default. + +=item B<dn_rev> + +reverse the fields of the DN. This is required by RFC2253. As a side +effect this also reverses the order of multiple AVAs but this is +permissible. + +=item B<nofname>, B<sname>, B<lname>, B<oid> + +these options alter how the field name is displayed. B<nofname> does +not display the field at all. B<sname> uses the "short name" form +(CN for commonName for example). B<lname> uses the long form. +B<oid> represents the OID in numerical form and is useful for +diagnostic purpose. + +=item B<align> + +align field values for a more readable output. Only usable with +B<sep_multiline>. + +=item B<space_eq> + +places spaces round the B<=> character which follows the field +name. + +=back + +=head2 Text Options + +As well as customising the name output format, it is also possible to +customise the actual fields printed using the B<certopt> options when +the B<text> option is present. The default behaviour is to print all fields. + +=over 4 + +=item B<compatible> + +use the old format. This is equivalent to specifying no output options at all. + +=item B<no_header> + +don't print header information: that is the lines saying "Certificate" and "Data". + +=item B<no_version> + +don't print out the version number. + +=item B<no_serial> + +don't print out the serial number. + +=item B<no_signame> + +don't print out the signature algorithm used. + +=item B<no_validity> + +don't print the validity, that is the B<notBefore> and B<notAfter> fields. + +=item B<no_subject> + +don't print out the subject name. + +=item B<no_issuer> + +don't print out the issuer name. + +=item B<no_pubkey> + +don't print out the public key. + +=item B<no_sigdump> + +don't give a hexadecimal dump of the certificate signature. + +=item B<no_aux> + +don't print out certificate trust information. + +=item B<no_extensions> + +don't print out any X509V3 extensions. + +=item B<ext_default> + +retain default extension behaviour: attempt to print out unsupported certificate extensions. + +=item B<ext_error> + +print an error message for unsupported certificate extensions. + +=item B<ext_parse> + +ASN1 parse unsupported extensions. + +=item B<ext_dump> + +hex dump unsupported extensions. + +=item B<ca_default> + +the value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>, +B<no_header>, and B<no_version>. + +=back + +=head1 EXAMPLES + +Note: in these examples the '\' means the example should be all on one +line. + +Display the contents of a certificate: + + openssl x509 -in cert.pem -noout -text + +Display the certificate serial number: + + openssl x509 -in cert.pem -noout -serial + +Display the certificate subject name: + + openssl x509 -in cert.pem -noout -subject + +Display the certificate subject name in RFC2253 form: + + openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 + +Display the certificate subject name in oneline form on a terminal +supporting UTF8: + + openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb + +Display the certificate SHA1 fingerprint: + + openssl x509 -sha1 -in cert.pem -noout -fingerprint + +Convert a certificate from PEM to DER format: + + openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER + +Convert a certificate to a certificate request: + + openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem + +Convert a certificate request into a self signed certificate using +extensions for a CA: + + openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \ + -signkey key.pem -out cacert.pem + +Sign a certificate request using the CA certificate above and add user +certificate extensions: + + openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \ + -CA cacert.pem -CAkey key.pem -CAcreateserial + + +Set a certificate to be trusted for SSL client use and change set its alias to +"Steve's Class 1 CA" + + openssl x509 -in cert.pem -addtrust clientAuth \ + -setalias "Steve's Class 1 CA" -out trust.pem + +=head1 NOTES + +The PEM format uses the header and footer lines: + + -----BEGIN CERTIFICATE----- + -----END CERTIFICATE----- + +it will also handle files containing: + + -----BEGIN X509 CERTIFICATE----- + -----END X509 CERTIFICATE----- + +Trusted certificates have the lines + + -----BEGIN TRUSTED CERTIFICATE----- + -----END TRUSTED CERTIFICATE----- + +The conversion to UTF8 format used with the name options assumes that +T61Strings use the ISO8859-1 character set. This is wrong but Netscape +and MSIE do this as do many certificates. So although this is incorrect +it is more likely to display the majority of certificates correctly. + +The B<-email> option searches the subject name and the subject alternative +name extension. Only unique email addresses will be printed out: it will +not print the same address more than once. + +=head1 CERTIFICATE EXTENSIONS + +The B<-purpose> option checks the certificate extensions and determines +what the certificate can be used for. The actual checks done are rather +complex and include various hacks and workarounds to handle broken +certificates and software. + +The same code is used when verifying untrusted certificates in chains +so this section is useful if a chain is rejected by the verify code. + +The basicConstraints extension CA flag is used to determine whether the +certificate can be used as a CA. If the CA flag is true then it is a CA, +if the CA flag is false then it is not a CA. B<All> CAs should have the +CA flag set to true. + +If the basicConstraints extension is absent then the certificate is +considered to be a "possible CA" other extensions are checked according +to the intended use of the certificate. A warning is given in this case +because the certificate should really not be regarded as a CA: however +it is allowed to be a CA to work around some broken software. + +If the certificate is a V1 certificate (and thus has no extensions) and +it is self signed it is also assumed to be a CA but a warning is again +given: this is to work around the problem of Verisign roots which are V1 +self signed certificates. + +If the keyUsage extension is present then additional restraints are +made on the uses of the certificate. A CA certificate B<must> have the +keyCertSign bit set if the keyUsage extension is present. + +The extended key usage extension places additional restrictions on the +certificate uses. If this extension is present (whether critical or not) +the key can only be used for the purposes specified. + +A complete description of each test is given below. The comments about +basicConstraints and keyUsage and V1 certificates above apply to B<all> +CA certificates. + + +=over 4 + +=item B<SSL Client> + +The extended key usage extension must be absent or include the "web client +authentication" OID. keyUsage must be absent or it must have the +digitalSignature bit set. Netscape certificate type must be absent or it must +have the SSL client bit set. + +=item B<SSL Client CA> + +The extended key usage extension must be absent or include the "web client +authentication" OID. Netscape certificate type must be absent or it must have +the SSL CA bit set: this is used as a work around if the basicConstraints +extension is absent. + +=item B<SSL Server> + +The extended key usage extension must be absent or include the "web server +authentication" and/or one of the SGC OIDs. keyUsage must be absent or it +must have the digitalSignature, the keyEncipherment set or both bits set. +Netscape certificate type must be absent or have the SSL server bit set. + +=item B<SSL Server CA> + +The extended key usage extension must be absent or include the "web server +authentication" and/or one of the SGC OIDs. Netscape certificate type must +be absent or the SSL CA bit must be set: this is used as a work around if the +basicConstraints extension is absent. + +=item B<Netscape SSL Server> + +For Netscape SSL clients to connect to an SSL server it must have the +keyEncipherment bit set if the keyUsage extension is present. This isn't +always valid because some cipher suites use the key for digital signing. +Otherwise it is the same as a normal SSL server. + +=item B<Common S/MIME Client Tests> + +The extended key usage extension must be absent or include the "email +protection" OID. Netscape certificate type must be absent or should have the +S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type +then the SSL client bit is tolerated as an alternative but a warning is shown: +this is because some Verisign certificates don't set the S/MIME bit. + +=item B<S/MIME Signing> + +In addition to the common S/MIME client tests the digitalSignature bit must +be set if the keyUsage extension is present. + +=item B<S/MIME Encryption> + +In addition to the common S/MIME tests the keyEncipherment bit must be set +if the keyUsage extension is present. + +=item B<S/MIME CA> + +The extended key usage extension must be absent or include the "email +protection" OID. Netscape certificate type must be absent or must have the +S/MIME CA bit set: this is used as a work around if the basicConstraints +extension is absent. + +=item B<CRL Signing> + +The keyUsage extension must be absent or it must have the CRL signing bit +set. + +=item B<CRL Signing CA> + +The normal CA tests apply. Except in this case the basicConstraints extension +must be present. + +=back + +=head1 BUGS + +Extensions in certificates are not transferred to certificate requests and +vice versa. + +It is possible to produce invalid certificates or requests by specifying the +wrong private key or using inconsistent options in some cases: these should +be checked. + +There should be options to explicitly set such things as start and end +dates rather than an offset from the current time. + +=head1 SEE ALSO + +L<req(1)>, L<ca(1)>, L<genrsa(1)>, +L<gendsa(1)>, L<verify(1)>, +L<x509v3_config(5)> + +=head1 HISTORY + +The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options +before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding +of the distinguished name. In OpenSSL 1.0.0 and later it is based on a +canonical version of the DN using SHA1. This means that any directories using +the old form must have their links rebuilt using B<c_rehash> or similar. + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/apps/x509v3_config.pod b/openssl-1.1.0h/doc/apps/x509v3_config.pod new file mode 100644 index 0000000..c0742c8 --- /dev/null +++ b/openssl-1.1.0h/doc/apps/x509v3_config.pod @@ -0,0 +1,541 @@ +=pod + +=for comment openssl_manual_section:5 + +=head1 NAME + +x509v3_config - X509 V3 certificate extension configuration format + +=head1 DESCRIPTION + +Several of the OpenSSL utilities can add extensions to a certificate or +certificate request based on the contents of a configuration file. + +Typically the application will contain an option to point to an extension +section. Each line of the extension section takes the form: + + extension_name=[critical,] extension_options + +If B<critical> is present then the extension will be critical. + +The format of B<extension_options> depends on the value of B<extension_name>. + +There are four main types of extension: I<string> extensions, I<multi-valued> +extensions, I<raw> and I<arbitrary> extensions. + +String extensions simply have a string which contains either the value itself +or how it is obtained. + +For example: + + nsComment="This is a Comment" + +Multi-valued extensions have a short form and a long form. The short form +is a list of names and values: + + basicConstraints=critical,CA:true,pathlen:1 + +The long form allows the values to be placed in a separate section: + + basicConstraints=critical,@bs_section + + [bs_section] + + CA=true + pathlen=1 + +Both forms are equivalent. + +The syntax of raw extensions is governed by the extension code: it can +for example contain data in multiple sections. The correct syntax to +use is defined by the extension code itself: check out the certificate +policies extension for an example. + +If an extension type is unsupported then the I<arbitrary> extension syntax +must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details. + +=head1 STANDARD EXTENSIONS + +The following sections describe each supported extension in detail. + +=head2 Basic Constraints. + +This is a multi valued extension which indicates whether a certificate is +a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or +B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an +non-negative value can be included. + +For example: + + basicConstraints=CA:TRUE + + basicConstraints=CA:FALSE + + basicConstraints=critical,CA:TRUE, pathlen:0 + +A CA certificate B<must> include the basicConstraints value with the CA field +set to TRUE. An end user certificate must either set CA to FALSE or exclude the +extension entirely. Some software may require the inclusion of basicConstraints +with CA set to FALSE for end entity certificates. + +The pathlen parameter indicates the maximum number of CAs that can appear +below this one in a chain. So if you have a CA with a pathlen of zero it can +only be used to sign end user certificates and not further CAs. + + +=head2 Key Usage. + +Key usage is a multi valued extension consisting of a list of names of the +permitted key usages. + +The supported names are: digitalSignature, nonRepudiation, keyEncipherment, +dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly +and decipherOnly. + +Examples: + + keyUsage=digitalSignature, nonRepudiation + + keyUsage=critical, keyCertSign + + +=head2 Extended Key Usage. + +This extensions consists of a list of usages indicating purposes for which +the certificate public key can be used for, + +These can either be object short names or the dotted numerical form of OIDs. +While any OID can be used only certain values make sense. In particular the +following PKIX, NS and MS values are meaningful: + + Value Meaning + ----- ------- + serverAuth SSL/TLS Web Server Authentication. + clientAuth SSL/TLS Web Client Authentication. + codeSigning Code signing. + emailProtection E-mail Protection (S/MIME). + timeStamping Trusted Timestamping + OCSPSigning OCSP Signing + ipsecIKE ipsec Internet Key Exchange + msCodeInd Microsoft Individual Code Signing (authenticode) + msCodeCom Microsoft Commercial Code Signing (authenticode) + msCTLSign Microsoft Trust List Signing + msEFS Microsoft Encrypted File System + +Examples: + + extendedKeyUsage=critical,codeSigning,1.2.3.4 + extendedKeyUsage=serverAuth,clientAuth + + +=head2 Subject Key Identifier. + +This is really a string extension and can take two possible values. Either +the word B<hash> which will automatically follow the guidelines in RFC3280 +or a hex string giving the extension value to include. The use of the hex +string is strongly discouraged. + +Example: + + subjectKeyIdentifier=hash + + +=head2 Authority Key Identifier. + +The authority key identifier extension permits two options. keyid and issuer: +both can take the optional value "always". + +If the keyid option is present an attempt is made to copy the subject key +identifier from the parent certificate. If the value "always" is present +then an error is returned if the option fails. + +The issuer option copies the issuer and serial number from the issuer +certificate. This will only be done if the keyid option fails or +is not included unless the "always" flag will always include the value. + +Example: + + authorityKeyIdentifier=keyid,issuer + + +=head2 Subject Alternative Name. + +The subject alternative name extension allows various literal values to be +included in the configuration file. These include B<email> (an email address) +B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a +registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName> +(a distinguished name) and otherName. + +The email option include a special 'copy' value. This will automatically +include any email addresses contained in the certificate subject name in +the extension. + +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 +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 +L<ASN1_generate_nconf(3)> format. + +Examples: + + subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ + subjectAltName=IP:192.168.7.1 + subjectAltName=IP:13::17 + subjectAltName=email:my@other.address,RID:1.2.3.4 + subjectAltName=otherName:1.2.3.4;UTF8:some other identifier + + subjectAltName=dirName:dir_sect + + [dir_sect] + C=UK + O=My Organization + OU=My Unit + CN=My Name + + +=head2 Issuer Alternative Name. + +The issuer alternative name option supports all the literal options of +subject alternative name. It does B<not> support the email:copy option because +that would not make sense. It does support an additional issuer:copy option +that will copy all the subject alternative name values from the issuer +certificate (if possible). + +Example: + + issuserAltName = issuer:copy + + +=head2 Authority Info Access. + +The authority information access extension gives details about how to access +certain information relating to the CA. Its syntax is accessOID;location +where I<location> has the same syntax as subject alternative name (except +that email:copy is not supported). accessOID can be any valid OID but only +certain values are meaningful, for example OCSP and caIssuers. + +Example: + + authorityInfoAccess = OCSP;URI:http://ocsp.my.host/ + authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html + + +=head2 CRL distribution points + +This is a multi-valued extension whose options can be either in name:value pair +using the same form as subject alternative name or a single value representing +a section name containing all the distribution point fields. + +For a name:value pair a new DistributionPoint with the fullName field set to +the given value both the cRLissuer and reasons fields are omitted in this case. + +In the single option case the section indicated contains values for each +field. In this section: + +If the name is "fullname" the value field should contain the full name +of the distribution point in the same format as subject alternative name. + +If the name is "relativename" then the value field should contain a section +name whose contents represent a DN fragment to be placed in this field. + +The name "CRLIssuer" if present should contain a value for this field in +subject alternative name format. + +If the name is "reasons" the value field should consist of a comma +separated field containing the reasons. Valid reasons are: "keyCompromise", +"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation", +"certificateHold", "privilegeWithdrawn" and "AACompromise". + + +Simple examples: + + crlDistributionPoints=URI:http://myhost.com/myca.crl + crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl + +Full distribution point example: + + crlDistributionPoints=crldp1_section + + [crldp1_section] + + fullname=URI:http://myhost.com/myca.crl + CRLissuer=dirName:issuer_sect + reasons=keyCompromise, CACompromise + + [issuer_sect] + C=UK + O=Organisation + CN=Some Name + +=head2 Issuing Distribution Point + +This extension should only appear in CRLs. It is a multi valued extension +whose syntax is similar to the "section" pointed to by the CRL distribution +points extension with a few differences. + +The names "reasons" and "CRLissuer" are not recognized. + +The name "onlysomereasons" is accepted which sets this field. The value is +in the same format as the CRL distribution point "reasons" field. + +The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted +the values should be a boolean value (TRUE or FALSE) to indicate the value of +the corresponding field. + +Example: + + issuingDistributionPoint=critical, @idp_section + + [idp_section] + + fullname=URI:http://myhost.com/myca.crl + indirectCRL=TRUE + onlysomereasons=keyCompromise, CACompromise + + [issuer_sect] + C=UK + O=Organisation + CN=Some Name + + +=head2 Certificate Policies. + +This is a I<raw> extension. All the fields of this extension can be set by +using the appropriate syntax. + +If you follow the PKIX recommendations and just using one OID then you just +include the value of that OID. Multiple OIDs can be set separated by commas, +for example: + + certificatePolicies= 1.2.4.5, 1.1.3.4 + +If you wish to include qualifiers then the policy OID and qualifiers need to +be specified in a separate section: this is done by using the @section syntax +instead of a literal OID value. + +The section referred to must include the policy OID using the name +policyIdentifier, cPSuri qualifiers can be included using the syntax: + + CPS.nnn=value + +userNotice qualifiers can be set using the syntax: + + userNotice.nnn=@notice + +The value of the userNotice qualifier is specified in the relevant section. +This section can include explicitText, organization and noticeNumbers +options. explicitText and organization are text strings, noticeNumbers is a +comma separated list of numbers. The organization and noticeNumbers options +(if included) must BOTH be present. If you use the userNotice option with IE5 +then you need the 'ia5org' option at the top level to modify the encoding: +otherwise it will not be interpreted properly. + +Example: + + certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect + + [polsect] + + policyIdentifier = 1.3.5.8 + CPS.1="http://my.host.name/" + CPS.2="http://my.your.name/" + userNotice.1=@notice + + [notice] + + explicitText="Explicit Text Here" + organization="Organisation Name" + noticeNumbers=1,2,3,4 + +The B<ia5org> option changes the type of the I<organization> field. In RFC2459 +it can only be of type DisplayText. In RFC3280 IA5String is also permissible. +Some software (for example some versions of MSIE) may require ia5org. + +=head2 Policy Constraints + +This is a multi-valued extension which consisting of the names +B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer +value. At least one component must be present. + +Example: + + policyConstraints = requireExplicitPolicy:3 + + +=head2 Inhibit Any Policy + +This is a string extension whose value must be a non negative integer. + +Example: + + inhibitAnyPolicy = 2 + + +=head2 Name Constraints + +The name constraints extension is a multi-valued extension. The name should +begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of +the name and the value follows the syntax of subjectAltName except email:copy +is not supported and the B<IP> form should consist of an IP addresses and +subnet mask separated by a B</>. + +Examples: + + nameConstraints=permitted;IP:192.168.0.0/255.255.0.0 + + nameConstraints=permitted;email:.somedomain.com + + nameConstraints=excluded;email:.com + + +=head2 OCSP No Check + +The OCSP No Check extension is a string extension but its value is ignored. + +Example: + + noCheck = ignored + + +=head2 TLS Feature (aka Must Staple) + +This is a multi-valued extension consisting of a list of TLS extension +identifiers. Each identifier may be a number (0..65535) or a supported name. +When a TLS client sends a listed extension, the TLS server is expected to +include that extension in its reply. + +The supported names are: B<status_request> and B<status_request_v2>. + +Example: + + tlsfeature = status_request + + +=head1 DEPRECATED EXTENSIONS + +The following extensions are non standard, Netscape specific and largely +obsolete. Their use in new applications is discouraged. + +=head2 Netscape String extensions. + +Netscape Comment (B<nsComment>) is a string extension containing a comment +which will be displayed when the certificate is viewed in some browsers. + +Example: + + nsComment = "Some Random Comment" + +Other supported extensions in this category are: B<nsBaseUrl>, +B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> +and B<nsSslServerName>. + + +=head2 Netscape Certificate Type + +This is a multi-valued extensions which consists of a list of flags to be +included. It was used to indicate the purposes for which a certificate could +be used. The basicConstraints, keyUsage and extended key usage extensions are +now used instead. + +Acceptable values for nsCertType are: B<client>, B<server>, B<email>, +B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. + + +=head1 ARBITRARY EXTENSIONS + +If an extension is not supported by the OpenSSL code then it must be encoded +using the arbitrary extension format. It is also possible to use the arbitrary +format for supported extensions. Extreme care should be taken to ensure that +the data is formatted correctly for the given extension type. + +There are two ways to encode arbitrary extensions. + +The first way is to use the word ASN1 followed by the extension content +using the same syntax as L<ASN1_generate_nconf(3)>. +For example: + + 1.2.3.4=critical,ASN1:UTF8String:Some random data + + 1.2.3.4=ASN1:SEQUENCE:seq_sect + + [seq_sect] + + field1 = UTF8:field1 + field2 = UTF8:field2 + +It is also possible to use the word DER to include the raw encoded data in any +extension. + + 1.2.3.4=critical,DER:01:02:03:04 + 1.2.3.4=DER:01020304 + +The value following DER is a hex dump of the DER encoding of the extension +Any extension can be placed in this form to override the default behaviour. +For example: + + basicConstraints=critical,DER:00:01:02:03 + +=head1 WARNING + +There is no guarantee that a specific implementation will process a given +extension. It may therefore be sometimes possible to use certificates for +purposes prohibited by their extensions because a specific application does +not recognize or honour the values of the relevant extensions. + +The DER and ASN1 options should be used with caution. It is possible to create +totally invalid extensions if they are not used carefully. + + +=head1 NOTES + +If an extension is multi-value and a field value must contain a comma the long +form must be used otherwise the comma would be misinterpreted as a field +separator. For example: + + subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar + +will produce an error but the equivalent form: + + subjectAltName=@subject_alt_section + + [subject_alt_section] + subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar + +is valid. + +Due to the behaviour of the OpenSSL B<conf> library the same field name +can only occur once in a section. This means that: + + subjectAltName=@alt_section + + [alt_section] + + email=steve@here + email=steve@there + +will only recognize the last value. This can be worked around by using the form: + + [alt_section] + + email.1=steve@here + email.2=steve@there + +=head1 SEE ALSO + +L<req(1)>, L<ca(1)>, L<x509(1)>, +L<ASN1_generate_nconf(3)> + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASN1_INTEGER_get_int64.pod b/openssl-1.1.0h/doc/crypto/ASN1_INTEGER_get_int64.pod new file mode 100644 index 0000000..f61268d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASN1_INTEGER_get_int64.pod @@ -0,0 +1,133 @@ +=pod + +=head1 NAME + +ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64, +ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN +- ASN.1 INTEGER and ENUMERATED utilities + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a); + int ASN1_INTEGER_get(const ASN1_INTEGER *a, long v); + + int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r); + long ASN1_INTEGER_set(const ASN1_INTEGER *a); + + int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a); + int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r); + + ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai); + BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn); + + int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a); + long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a); + + int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r); + int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v); + + ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai); + BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn); + +=head1 DESCRIPTION + +These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED> +structures. + +ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type +If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails +(due to invalid type or the value being too big to fit into an B<int64_t> type) +it returns 0. + +ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it +converts to a B<uint64_t> type and an error is returned if the passed integer +is negative. + +ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is +NULL and -1 on error (which is ambiguous because -1 is a legitimate value for +an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64() +instead. + +ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the +B<int64_t> value B<r>. + +ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> B<a> to the +B<uint64_t> value B<r>. + +ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value +B<v>. + +BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai> +is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then +the existing structure will be used instead. + +ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is +NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the +existing structure will be used instead. + +ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(), +ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN() +behave in an identical way to their ASN1_INTEGER counterparts except they +operate on an B<ASN1_ENUMERATED> value. + +ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to +ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not +fit in a long type. New applications should use ASN1_ENUMERATED_get_int64() +instead. + +=head1 NOTES + +In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an +integer of almost arbitrary size and so cannot always be represented by a C +B<int64_t> type. However in many cases (for example version numbers) they +represent small integers which can be more easily manipulated if converted to +an appropriate C integer type. + +=head1 BUGS + +The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get() +mean these functions should be avoided if possible. They are retained for +compatibility. Normally the ambiguous return values are not legitimate +values for the fields they represent. + +=head1 RETURN VALUES + +ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and +ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only +fail if a memory allocation error occurs. + +ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success +and 0 for failure. They will fail if the passed type is incorrect (this will +only happen if there is a programming error) or if the value exceeds the range +of an B<int64_t> type. + +BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or +B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will +only fail due to a memory allocation error. + +ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure +of NULL if an error occurs. They can fail if the passed type is incorrect +(due to programming error) or due to a memory allocation failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 HISTORY + +ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(), +ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64() +were added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASN1_OBJECT_new.pod b/openssl-1.1.0h/doc/crypto/ASN1_OBJECT_new.pod new file mode 100644 index 0000000..4c018ef --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASN1_OBJECT_new.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + ASN1_OBJECT *ASN1_OBJECT_new(void); + void ASN1_OBJECT_free(ASN1_OBJECT *a); + +=head1 DESCRIPTION + +The ASN1_OBJECT allocation routines, allocate and free an +ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER. + +ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure. + +ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>. +If B<a> is NULL, nothing is done. + +=head1 NOTES + +Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it +is almost never used in applications. The ASN1 object utility functions +such as OBJ_nid2obj() are used instead. + +=head1 RETURN VALUES + +If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)>. +Otherwise it returns a pointer to the newly allocated structure. + +ASN1_OBJECT_free() returns no value. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASN1_STRING_length.pod b/openssl-1.1.0h/doc/crypto/ASN1_STRING_length.pod new file mode 100644 index 0000000..20a372d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASN1_STRING_length.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, +ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, +ASN1_STRING_to_UTF8 - ASN1_STRING utility functions + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + int ASN1_STRING_length(ASN1_STRING *x); + const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x); + unsigned char * ASN1_STRING_data(ASN1_STRING *x); + + ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a); + + int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b); + + int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len); + + int ASN1_STRING_type(const ASN1_STRING *x); + + int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in); + +=head1 DESCRIPTION + +These functions allow an B<ASN1_STRING> structure to be manipulated. + +ASN1_STRING_length() returns the length of the content of B<x>. + +ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>. +Since this is an internal pointer it should B<not> be freed or +modified in any way. + +ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the +returned value is not constant. This function is deprecated: +applications should use ASN1_STRING_get0_data() instead. + +ASN1_STRING_dup() returns a copy of the structure B<a>. + +ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two +are identical. The string types and content are compared. + +ASN1_STRING_set() sets the data of string B<str> to the buffer +B<data> or length B<len>. The supplied data is copied. If B<len> +is -1 then the length is determined by strlen(data). + +ASN1_STRING_type() returns the type of B<x>, using standard constants +such as B<V_ASN1_OCTET_STRING>. + +ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the +converted data is allocated in a buffer in B<*out>. The length of +B<out> is returned or a negative error code. The buffer B<*out> +should be freed using OPENSSL_free(). + +=head1 NOTES + +Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING> +structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed +to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents. +B<ASN1_STRING> is also used for some B<CHOICE> types which consist +entirely of primitive string types such as B<DirectoryString> and +B<Time>. + +These functions should B<not> be used to examine or modify B<ASN1_INTEGER> +or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED> +utility functions should be used instead. + +In general it cannot be assumed that the data returned by ASN1_STRING_data() +is null terminated or does not contain embedded nulls. The actual format +of the data will depend on the actual string type itself: for example +for an IA5String the data will be ASCII, for a BMPString two bytes per +character in big endian format, and for an UTF8String it will be in UTF8 format. + +Similar care should be take to ensure the data is in the correct format +when calling ASN1_STRING_set(). + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASN1_STRING_new.pod b/openssl-1.1.0h/doc/crypto/ASN1_STRING_new.pod new file mode 100644 index 0000000..7bd2fc1 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASN1_STRING_new.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free - +ASN1_STRING allocation functions + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + ASN1_STRING * ASN1_STRING_new(void); + ASN1_STRING * ASN1_STRING_type_new(int type); + void ASN1_STRING_free(ASN1_STRING *a); + +=head1 DESCRIPTION + +ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type +is undefined. + +ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of +type B<type>. + +ASN1_STRING_free() frees up B<a>. +If B<a> is NULL nothing is done. + +=head1 NOTES + +Other string types call the B<ASN1_STRING> functions. For example +ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING). + +=head1 RETURN VALUES + +ASN1_STRING_new() and ASN1_STRING_type_new() return a valid +ASN1_STRING structure or B<NULL> if an error occurred. + +ASN1_STRING_free() does not return a value. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASN1_STRING_print_ex.pod b/openssl-1.1.0h/doc/crypto/ASN1_STRING_print_ex.pod new file mode 100644 index 0000000..a521f78 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASN1_STRING_print_ex.pod @@ -0,0 +1,105 @@ +=pod + +=head1 NAME + +ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print +- ASN1_STRING output routines + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags); + int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags); + int ASN1_STRING_print(BIO *out, const ASN1_STRING *str); + + const char *ASN1_tag2str(int tag); + +=head1 DESCRIPTION + +These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to +represent all the ASN1 string types. + +ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by +the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs +to B<fp> instead. + +ASN1_STRING_print() prints B<str> to B<out> but using a different format to +ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF) +with '.'. + +ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>. + +=head1 NOTES + +ASN1_STRING_print() is a legacy function which should be avoided in new applications. + +Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is +suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>. + +The complete set of supported options for B<flags> is listed below. + +Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters +determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control +characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the +MSB set are escaped: this option should B<not> be used if the terminal correctly +interprets UTF8 sequences. + +Escaping takes several forms. + +If the character being escaped is a 16 bit character then the form "\UXXXX" is used +using exactly four characters for the hex representation. If it is 32 bits then +"\WXXXXXXXX" is used using eight characters of its hex representation. These forms +will only be used if UTF8 conversion is not set (see below). + +Printable characters are normally escaped using the backslash '\' character. If +B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by +double quote characters: this is arguably more readable than the backslash +notation. Other characters use the "\XX" using exactly two characters of the hex +representation. + +If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8 +format first. If the terminal supports the display of UTF8 sequences then this +option will correctly display multi byte characters. + +If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at +all: everything is assumed to be one byte per character. This is primarily for +debugging purposes and can result in confusing output in multi character strings. + +If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out +before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str(). + +The content of a string instead of being interpreted can be "dumped": this just +outputs the value of the string using the form #XXXX using hex format for each +octet. + +If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped. + +Normally non character string types (such as OCTET STRING) are assumed to be +one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will +be dumped instead. + +When a type is dumped normally just the content octets are printed, if +B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped +instead (including tag and length octets). + +B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is +equivalent to: + ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | + ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER + +=head1 SEE ALSO + +L<X509_NAME_print_ex(3)>, +L<ASN1_tag2str(3)> + +=head1 COPYRIGHT + +Copyright 2002-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASN1_TIME_set.pod b/openssl-1.1.0h/doc/crypto/ASN1_TIME_set.pod new file mode 100644 index 0000000..457b721 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASN1_TIME_set.pod @@ -0,0 +1,138 @@ +=pod + +=head1 NAME + +ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string, +ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions + +=head1 SYNOPSIS + + ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t); + ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, + int offset_day, long offset_sec); + int ASN1_TIME_set_string(ASN1_TIME *s, const char *str); + int ASN1_TIME_check(const ASN1_TIME *t); + int ASN1_TIME_print(BIO *b, const ASN1_TIME *s); + + int ASN1_TIME_diff(int *pday, int *psec, + const ASN1_TIME *from, const ASN1_TIME *to); + +=head1 DESCRIPTION + +The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the +time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME +structure is allocated and returned. + +ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented +by the time B<offset_day> and B<offset_sec> after the time_t value B<t>. +The values of B<offset_day> or B<offset_sec> can be negative to set a +time before B<t>. The B<offset_sec> value can also exceed the number of +seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated +and returned. + +ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time +represented by string B<str> which must be in appropriate ASN.1 time +format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). + +ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>. + +ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable +format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example +"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time +structure has invalid format it prints out "Bad time value" and returns +an error. + +ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between +B<from> and B<to>. If B<to> represents a time later than B<from> then +one or both (depending on the time difference) of B<*pday> and B<*psec> +will be positive. If B<to> represents a time earlier than B<from> then +one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from> +represent the same time then B<*pday> and B<*psec> will both be zero. +If both B<*pday> and B<*psec> are non-zero they will always have the same +sign. The value of B<*psec> will always be less than the number of seconds +in a day. If B<from> or B<to> is NULL the current time is used. + +=head1 NOTES + +The ASN1_TIME structure corresponds to the ASN.1 structure B<Time> +defined in RFC5280 et al. The time setting functions obey the rules outlined +in RFC5280: if the date can be represented by UTCTime it is used, else +GeneralizedTime is used. + +The ASN1_TIME structure is represented as an ASN1_STRING internally and can +be freed up using ASN1_STRING_free(). + +The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt +is made to correct ancient calendar changes (for example from Julian to +Gregorian calendars). + +Some applications add offset times directly to a time_t value and pass the +results to ASN1_TIME_set() (or equivalent). This can cause problems as the +time_t value can overflow on some systems resulting in unexpected results. +New applications should use ASN1_TIME_adj() instead and pass the offset value +in the B<offset_sec> and B<offset_day> parameters instead of directly +manipulating a time_t value. + +=head1 BUGS + +ASN1_TIME_print() currently does not print out the time zone: it either prints +out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT +anyway. + +=head1 EXAMPLES + +Set a time structure to one hour after the current time and print it out: + + #include <time.h> + #include <openssl/asn1.h> + ASN1_TIME *tm; + time_t t; + BIO *b; + t = time(NULL); + tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60); + b = BIO_new_fp(stdout, BIO_NOCLOSE); + ASN1_TIME_print(b, tm); + ASN1_STRING_free(tm); + BIO_free(b); + +Determine if one time is later or sooner than the current time: + + int day, sec; + + if (!ASN1_TIME_diff(&day, &sec, NULL, to)) + /* Invalid time format */ + + if (day > 0 || sec > 0) + printf("Later\n"); + else if (day < 0 || sec < 0) + printf("Sooner\n"); + else + printf("Same\n"); + +=head1 RETURN VALUES + +ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure +or NULL if an error occurred. + +ASN1_TIME_set_string() returns 1 if the time value is successfully set and +0 otherwise. + +ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0 +otherwise. + +ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if +an error occurred (I/O error or invalid time format). + +ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the +pass ASN1_TIME structure has invalid syntax for example. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASN1_TYPE_get.pod b/openssl-1.1.0h/doc/crypto/ASN1_TYPE_get.pod new file mode 100644 index 0000000..70c5687 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASN1_TYPE_get.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility +functions + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + int ASN1_TYPE_get(const ASN1_TYPE *a); + void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value); + int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value); + int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b); + + void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t); + ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s, + ASN1_TYPE **t); + +=head1 DESCRIPTION + +These functions allow an ASN1_TYPE structure to be manipulated. The +ASN1_TYPE structure can contain any ASN.1 type or constructed type +such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type. + +ASN1_TYPE_get() returns the type of B<a>. + +ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This +function uses the pointer B<value> internally so it must B<not> be freed +up after the call. + +ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>. + +ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if +they are identical and non-zero otherwise. + +ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in +B<t> using the ASN.1 structure B<it>. If successful it returns a pointer +to the ASN.1 structure corresponding to B<it> which must be freed by the +caller. If it fails it return NULL. + +ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s> +corresponding to B<it> into an ASN1_TYPE. If successful the encoded +ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type +is written to B<t> overwriting any existing data. If B<t> is not NULL +but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>. + +=head1 NOTES + +The type and meaning of the B<value> parameter for ASN1_TYPE_set() and +ASN1_TYPE_set1() is determined by the B<type> parameter. +If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN +then the boolean is set to TRUE if B<value> is not NULL. If B<type> is +V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type> +is and ASN1_STRING structure. If B<type> corresponds to a primitive type +(or a string type) then the contents of the ASN1_STRING contain the content +octets of the type. If B<type> corresponds to a constructed type or +a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the +ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and +length octets). + +ASN1_TYPE_cmp() may not return zero if two types are equivalent but have +different encodings. For example the single content octet of the boolean TRUE +value under BER can have any non-zero encoding but ASN1_TYPE_cmp() will +only return zero if the values are the same. + +If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the +return value is non-zero. Technically if both parameters are NULL the two +types could be absent OPTIONAL fields and so should match, however passing +NULL values could also indicate a programming error (for example an +unparseable type which returns NULL) for types which do B<not> match. So +applications should handle the case of two absent values separately. + +=head1 RETURN VALUES + +ASN1_TYPE_get() returns the type of the ASN1_TYPE argument. + +ASN1_TYPE_set() does not return a value. + +ASN1_TYPE_set1() returns 1 for success and 0 for failure. + +ASN1_TYPE_cmp() returns 0 if the types are identical and non-zero otherwise. + +ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or +NULL on failure. + +ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or +NULL on failure. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASN1_generate_nconf.pod b/openssl-1.1.0h/doc/crypto/ASN1_generate_nconf.pod new file mode 100644 index 0000000..bf29af6 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASN1_generate_nconf.pod @@ -0,0 +1,270 @@ +=pod + +=head1 NAME + +ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf); + ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf); + +=head1 DESCRIPTION + +These functions generate the ASN1 encoding of a string +in an B<ASN1_TYPE> structure. + +B<str> contains the string to encode B<nconf> or B<cnf> contains +the optional configuration information where additional strings +will be read from. B<nconf> will typically come from a config +file whereas B<cnf> is obtained from an B<X509V3_CTX> structure +which will typically be used by X509 v3 certificate extension +functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional +configuration will be used. + +=head1 GENERATION STRING FORMAT + +The actual data encoded is determined by the string B<str> and +the configuration information. The general format of the string +is: + +=over 4 + +=item B<[modifier,]type[:value]> + +=back + +That is zero or more comma separated modifiers followed by a type +followed by an optional colon and a value. The formats of B<type>, +B<value> and B<modifier> are explained below. + +=head2 Supported Types + +The supported types are listed below. Unless otherwise specified +only the B<ASCII> format is permissible. + +=over 4 + +=item B<BOOLEAN>, B<BOOL> + +This encodes a boolean type. The B<value> string is mandatory and +should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>, +B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no> +are acceptable. + +=item B<NULL> + +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 prefaced by a minus sign and +is normally interpreted as a decimal value unless the prefix B<0x> +is included. + +=item B<ENUMERATED>, B<ENUM> + +Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to +B<INTEGER>. + +=item B<OBJECT>, B<OID> + +Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be +a short name, a long name or numerical format. + +=item B<UTCTIME>, B<UTC> + +Encodes an ASN1 B<UTCTime> structure, the value should be in +the format B<YYMMDDHHMMSSZ>. + +=item B<GENERALIZEDTIME>, B<GENTIME> + +Encodes an ASN1 B<GeneralizedTime> structure, the value should be in +the format B<YYYYMMDDHHMMSSZ>. + +=item B<OCTETSTRING>, B<OCT> + +Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents +of this structure, the format strings B<ASCII> and B<HEX> can be +used to specify the format of B<value>. + +=item B<BITSTRING>, B<BITSTR> + +Encodes an ASN1 B<BIT STRING>. B<value> represents the contents +of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST> +can be used to specify the format of B<value>. + +If the format is anything other than B<BITLIST> the number of unused +bits is set to zero. + +=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>, +B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>, +B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>, +B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>, +B<NUMERIC> + +These encode the corresponding string types. B<value> represents the +contents of this structure. The format can be B<ASCII> or B<UTF8>. + +=item B<SEQUENCE>, B<SEQ>, B<SET> + +Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value> +should be a section name which will contain the contents. The +field names in the section are ignored and the values are in the +generated string format. If B<value> is absent then an empty SEQUENCE +will be encoded. + +=back + +=head2 Modifiers + +Modifiers affect the following structure, they can be used to +add EXPLICIT or IMPLICIT tagging, add wrappers or to change +the string format of the final type and value. The supported +formats are documented below. + +=over 4 + +=item B<EXPLICIT>, B<EXP> + +Add an explicit tag to the following structure. This string +should be followed by a colon and the tag value to use as a +decimal value. + +By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL, +APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used, +the default is CONTEXT SPECIFIC. + +=item B<IMPLICIT>, B<IMP> + +This is the same as B<EXPLICIT> except IMPLICIT tagging is used +instead. + +=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP> + +The following structure is surrounded by an OCTET STRING, a SEQUENCE, +a SET or a BIT STRING respectively. For a BIT STRING the number of unused +bits is set to zero. + +=item B<FORMAT> + +This specifies the format of the ultimate value. It should be followed +by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>. + +If no format specifier is included then B<ASCII> is used. If B<UTF8> is +specified then the value string must be a valid B<UTF8> string. For B<HEX> the +output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT +STRING) is a comma separated list of the indices of the set bits, all other +bits are zero. + +=back + +=head1 EXAMPLES + +A simple IA5String: + + IA5STRING:Hello World + +An IA5String explicitly tagged: + + EXPLICIT:0,IA5STRING:Hello World + +An IA5String explicitly tagged using APPLICATION tagging: + + EXPLICIT:0A,IA5STRING:Hello World + +A BITSTRING with bits 1 and 5 set and all others zero: + + FORMAT:BITLIST,BITSTRING:1,5 + +A more complex example using a config file to produce a +SEQUENCE consisting of a BOOL an OID and a UTF8String: + + asn1 = SEQUENCE:seq_section + + [seq_section] + + field1 = BOOLEAN:TRUE + field2 = OID:commonName + field3 = UTF8:Third field + +This example produces an RSAPrivateKey structure, this is the +key contained in the file client.pem in all OpenSSL distributions +(note: the field names such as 'coeff' are ignored and are present just +for clarity): + + asn1=SEQUENCE:private_key + [private_key] + version=INTEGER:0 + + n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\ + D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 + + e=INTEGER:0x010001 + + d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\ + F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D + + p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\ + D4BD57 + + q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\ + 46EC4F + + exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\ + 9C0A39B9 + + exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\ + E7B2458F + + coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\ + 628657053A + +This example is the corresponding public key in a SubjectPublicKeyInfo +structure: + + # Start with a SEQUENCE + asn1=SEQUENCE:pubkeyinfo + + # pubkeyinfo contains an algorithm identifier and the public key wrapped + # in a BIT STRING + [pubkeyinfo] + algorithm=SEQUENCE:rsa_alg + pubkey=BITWRAP,SEQUENCE:rsapubkey + + # algorithm ID for RSA is just an OID and a NULL + [rsa_alg] + algorithm=OID:rsaEncryption + parameter=NULL + + # Actual public key: modulus and exponent + [rsapubkey] + n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\ + D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9 + + e=INTEGER:0x010001 + +=head1 RETURN VALUES + +ASN1_generate_nconf() and ASN1_generate_v3() return the encoded +data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred. + +The error codes that can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASYNC_WAIT_CTX_new.pod b/openssl-1.1.0h/doc/crypto/ASYNC_WAIT_CTX_new.pod new file mode 100644 index 0000000..2fb00a3 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASYNC_WAIT_CTX_new.pod @@ -0,0 +1,144 @@ +=pod + +=head1 NAME + +ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, +ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage +waiting for asynchronous jobs to complete + +=head1 SYNOPSIS + + #include <openssl/async.h> + + ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void); + void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx); + int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key, + OSSL_ASYNC_FD fd, + void *custom_data, + void (*cleanup)(ASYNC_WAIT_CTX *, const void *, + OSSL_ASYNC_FD, void *)); + int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key, + OSSL_ASYNC_FD *fd, void **custom_data); + int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd, + size_t *numfds); + int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd, + size_t *numaddfds, OSSL_ASYNC_FD *delfd, + size_t *numdelfds); + int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key); + + +=head1 DESCRIPTION + +For an overview of how asynchronous operations are implemented in OpenSSL see +L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous +"session", i.e. a related set of crypto operations. For example in SSL terms +this would have a one-to-one correspondence with an SSL connection. + +Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new() +function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When +the job is started it is associated with the ASYNC_WAIT_CTX for the duration of +that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one +time, but can be reused after an ASYNC_JOB has finished for a subsequent +ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed), +application code cleans up with ASYNC_WAIT_CTX_free(). + +ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling +ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in +the B<ctx> parameter will return the wait file descriptors associated with that +job in B<*fd>. The number of file descriptors returned will be stored in +B<*numfds>. It is the caller's responsibility to ensure that sufficient memory +has been allocated in B<*fd> to receive all the file descriptors. Calling +ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file +descriptors but will still populate B<*numfds>. Therefore application code is +typically expected to call this function twice: once to get the number of fds, +and then again when sufficient memory has been allocated. If only one +asynchronous engine is being used then normally this call will only ever return +one fd. If multiple asynchronous engines are being used then more could be +returned. + +The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds +have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE +result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has +been received). The B<numaddfds> and B<numdelfds> parameters will be populated +with the number of fds added or deleted respectively. B<*addfd> and B<*delfd> +will be populated with the list of added and deleted fds respectively. Similarly +to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not +NULL then the caller is responsible for ensuring sufficient memory is allocated. + +Implementors of async aware code (e.g. engines) are encouraged to return a +stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn" +of regularly changing fds - although no guarantees of this are provided to +applications. + +Applications can wait for the file descriptor to be ready for "read" using a +system function call such as select or poll (being ready for "read" indicates +that the job should be resumed). If no file descriptor is made available then an +application will have to periodically "poll" the job by attempting to restart it +to see if it is ready to continue. + +Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job +via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting +on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an +engine immediately prior to calling ASYNC_pause_job() and not by end user code. +An existing association with a file descriptor can be obtained using +ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of +these functions requires a B<key> value which is unique to the async aware +code. This could be any unique value but a good candidate might be the +B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and +will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The +ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup" +routine. This can be NULL but if provided will automatically get called when +the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the +fd or any other resources. Note: The "cleanup" routine does not get called if +the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd(). + +An example of typical usage might be an async capable engine. User code would +initiate cryptographic operations. The engine would initiate those operations +asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by +ASYNC_pause_job() to return control to the user code. The user code can then +perform other tasks or wait for the job to be ready by calling "select" or other +similar function on the wait file descriptor. The engine can signal to the user +code that the job should be resumed by making the wait file descriptor +"readable". Once resumed the engine should clear the wake signal on the wait +file descriptor. + +=head1 RETURN VALUES + +ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or +NULL on error. + +ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on +success or 0 on error. + +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + +=head1 SEE ALSO + +L<crypto(3)>, L<ASYNC_start_job(3)> + +=head1 HISTORY + +ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, +ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ASYNC_start_job.pod b/openssl-1.1.0h/doc/crypto/ASYNC_start_job.pod new file mode 100644 index 0000000..c10a66f --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ASYNC_start_job.pod @@ -0,0 +1,330 @@ +=pod + +=head1 NAME + +ASYNC_get_wait_ctx, +ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, +ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable +- asynchronous job management functions + +=head1 SYNOPSIS + + #include <openssl/async.h> + + int ASYNC_init_thread(size_t max_size, size_t init_size); + void ASYNC_cleanup_thread(void); + + int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret, + int (*func)(void *), void *args, size_t size); + int ASYNC_pause_job(void); + + ASYNC_JOB *ASYNC_get_current_job(void); + ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job); + void ASYNC_block_pause(void); + void ASYNC_unblock_pause(void); + + int ASYNC_is_capable(void); + +=head1 DESCRIPTION + +OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This +represents code that can be started and executes until some event occurs. At +that point the code can be paused and control returns to user code until some +subsequent event indicates that the job can be resumed. + +The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for +efficiency reasons, jobs can be created up front and reused many times. They are +held in a pool until they are needed, at which point they are removed from the +pool, used, and then returned to the pool when the job completes. If the user +application is multi-threaded, then ASYNC_init_thread() may be called for each +thread that will initiate asynchronous jobs. Before +user code exits per-thread resources need to be cleaned up. This will normally +occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly +initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be +outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to +ensure this will result in memory leaks. + +The B<max_size> argument limits the number of ASYNC_JOBs that will be held in +the pool. If B<max_size> is set to 0 then no upper limit is set. When an +ASYNC_JOB is needed but there are none available in the pool already then one +will be automatically created, as long as the total of ASYNC_JOBs managed by the +pool does not exceed B<max_size>. When the pool is first initialised +B<init_size> ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is +not called before the pool is first used then it will be called automatically +with a B<max_size> of 0 (no upper limit) and an B<init_size> of 0 (no ASYNC_JOBs +created up front). + +An asynchronous job is started by calling the ASYNC_start_job() function. +Initially B<*job> should be NULL. B<ctx> should point to an ASYNC_WAIT_CTX +object created through the L<ASYNC_WAIT_CTX_new(3)> function. B<ret> should +point to a location where the return value of the asynchronous function should +be stored on completion of the job. B<func> represents the function that should +be started asynchronously. The data pointed to by B<args> and of size B<size> +will be copied and then passed as an argument to B<func> when the job starts. +ASYNC_start_job will return one of the following values: + +=over 4 + +=item B<ASYNC_ERR> + +An error occurred trying to start the job. Check the OpenSSL error queue (e.g. +see L<ERR_print_errors(3)>) for more details. + +=item B<ASYNC_NO_JOBS> + +There are no jobs currently available in the pool. This call can be retried +again at a later time. + +=item B<ASYNC_PAUSE> + +The job was successfully started but was "paused" before it completed (see +ASYNC_pause_job() below). A handle to the job is placed in B<*job>. Other work +can be performed (if desired) and the job restarted at a later time. To restart +a job call ASYNC_start_job() again passing the job handle in B<*job>. The +B<func>, B<args> and B<size> parameters will be ignored when restarting a job. +When restarting a job ASYNC_start_job() B<must> be called from the same thread +that the job was originally started from. + +=item B<ASYNC_FINISH> + +The job completed. B<*job> will be NULL and the return value from B<func> will +be placed in B<*ret>. + +=back + +At any one time there can be a maximum of one job actively running per thread +(you can have many that are paused). ASYNC_get_current_job() can be used to get +a pointer to the currently executing ASYNC_JOB. If no job is currently executing +then this will return NULL. + +If executing within the context of a job (i.e. having been called directly or +indirectly by the function "func" passed as an argument to ASYNC_start_job()) +then ASYNC_pause_job() will immediately return control to the calling +application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A +subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the +B<*job> parameter will resume execution from the ASYNC_pause_job() call. If +ASYNC_pause_job() is called whilst not within the context of a job then no +action is taken and ASYNC_pause_job() returns immediately. + +ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX +for the B<job>. ASYNC_WAIT_CTXs can have a "wait" file descriptor associated +with them. Applications can wait for the file descriptor to be ready for "read" +using a system function call such as select or poll (being ready for "read" +indicates that the job should be resumed). If no file descriptor is made +available then an application will have to periodically "poll" the job by +attempting to restart it to see if it is ready to continue. + +An example of typical usage might be an async capable engine. User code would +initiate cryptographic operations. The engine would initiate those operations +asynchronously and then call L<ASYNC_WAIT_CTX_set_wait_fd(3)> followed by +ASYNC_pause_job() to return control to the user code. The user code can then +perform other tasks or wait for the job to be ready by calling "select" or other +similar function on the wait file descriptor. The engine can signal to the user +code that the job should be resumed by making the wait file descriptor +"readable". Once resumed the engine should clear the wake signal on the wait +file descriptor. + +The ASYNC_block_pause() function will prevent the currently active job from +pausing. The block will remain in place until a subsequent call to +ASYNC_unblock_pause(). These functions can be nested, e.g. if you call +ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in +order to re-enable pausing. If these functions are called while there is no +currently active job then they have no effect. This functionality can be useful +to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an +application acquires a lock. It then calls some cryptographic function which +invokes ASYNC_pause_job(). This returns control back to the code that created +the ASYNC_JOB. If that code then attempts to acquire the same lock before +resuming the original job then a deadlock can occur. By calling +ASYNC_block_pause() immediately after acquiring the lock and +ASYNC_unblock_pause() immediately before releasing it then this situation cannot +occur. + +Some platforms cannot support async operations. The ASYNC_is_capable() function +can be used to detect whether the current platform is async capable or not. + +=head1 RETURN VALUES + +ASYNC_init_thread returns 1 on success or 0 otherwise. + +ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or +ASYNC_FINISH as described above. + +ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when +not within the context of an ASYNC_JOB then this is counted as success so 1 is +returned. + +ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or +NULL if not within the context of a job. + +ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job. + +ASYNC_is_capable() returns 1 if the current platform is async capable or 0 +otherwise. + +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + +=head1 EXAMPLE + +The following example demonstrates how to use most of the core async APIs: + + #ifdef _WIN32 + # include <windows.h> + #endif + #include <stdio.h> + #include <unistd.h> + #include <openssl/async.h> + #include <openssl/crypto.h> + + int unique = 0; + + void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw) + { + OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw; + close(r); + close(*w); + OPENSSL_free(w); + } + + int jobfunc(void *arg) + { + ASYNC_JOB *currjob; + unsigned char *msg; + int pipefds[2] = {0, 0}; + OSSL_ASYNC_FD *wptr; + char buf = 'X'; + + currjob = ASYNC_get_current_job(); + if (currjob != NULL) { + printf("Executing within a job\n"); + } else { + printf("Not executing within a job - should not happen\n"); + return 0; + } + + msg = (unsigned char *)arg; + printf("Passed in message is: %s\n", msg); + + if (pipe(pipefds) != 0) { + printf("Failed to create pipe\n"); + return 0; + } + wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD)); + if (wptr == NULL) { + printf("Failed to malloc\n"); + return 0; + } + *wptr = pipefds[1]; + ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique, + pipefds[0], wptr, cleanup); + + /* + * Normally some external event would cause this to happen at some + * later point - but we do it here for demo purposes, i.e. + * immediately signalling that the job is ready to be woken up after + * we return to main via ASYNC_pause_job(). + */ + write(pipefds[1], &buf, 1); + + /* Return control back to main */ + ASYNC_pause_job(); + + /* Clear the wake signal */ + read(pipefds[0], &buf, 1); + + printf ("Resumed the job after a pause\n"); + + return 1; + } + + int main(void) + { + ASYNC_JOB *job = NULL; + ASYNC_WAIT_CTX *ctx = NULL; + int ret; + OSSL_ASYNC_FD waitfd; + fd_set waitfdset; + size_t numfds; + unsigned char msg[13] = "Hello world!"; + + printf("Starting...\n"); + + ctx = ASYNC_WAIT_CTX_new(); + if (ctx == NULL) { + printf("Failed to create ASYNC_WAIT_CTX\n"); + abort(); + } + + for (;;) { + switch(ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) { + case ASYNC_ERR: + case ASYNC_NO_JOBS: + printf("An error occurred\n"); + goto end; + case ASYNC_PAUSE: + printf("Job was paused\n"); + break; + case ASYNC_FINISH: + printf("Job finished with return value %d\n", ret); + goto end; + } + + /* Wait for the job to be woken */ + printf("Waiting for the job to be woken up\n"); + + if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds) + || numfds > 1) { + printf("Unexpected number of fds\n"); + abort(); + } + ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds); + FD_ZERO(&waitfdset); + FD_SET(waitfd, &waitfdset); + select(waitfd + 1, &waitfdset, NULL, NULL, NULL); + } + + end: + ASYNC_WAIT_CTX_free(ctx); + printf("Finishing\n"); + + return 0; + } + +The expected output from executing the above example program is: + + Starting... + Executing within a job + Passed in message is: Hello world! + Job was paused + Waiting for the job to be woken up + Resumed the job after a pause + Job finished with return value 1 + Finishing + +=head1 SEE ALSO + +L<crypto(3)>, L<ERR_print_errors(3)> + +=head1 HISTORY + +ASYNC_init_thread, ASYNC_cleanup_thread, +ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(), +ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first +added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BF_encrypt.pod b/openssl-1.1.0h/doc/crypto/BF_encrypt.pod new file mode 100644 index 0000000..0401e90 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BF_encrypt.pod @@ -0,0 +1,117 @@ +=pod + +=head1 NAME + +BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, +BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption + +=head1 SYNOPSIS + + #include <openssl/blowfish.h> + + void BF_set_key(BF_KEY *key, int len, const unsigned char *data); + + void BF_ecb_encrypt(const unsigned char *in, unsigned char *out, + BF_KEY *key, int enc); + void BF_cbc_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int enc); + void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int *num, + int enc); + void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int *num); + const char *BF_options(void); + + void BF_encrypt(BF_LONG *data, const BF_KEY *key); + void BF_decrypt(BF_LONG *data, const BF_KEY *key); + +=head1 DESCRIPTION + +This library implements the Blowfish cipher, which was invented and described +by Counterpane (see http://www.counterpane.com/blowfish.html ). + +Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. +It uses a variable size key, but typically, 128 bit (16 byte) keys are +considered good for strong encryption. Blowfish can be used in the same +modes as DES (see L<des_modes(7)>). Blowfish is currently one +of the faster block ciphers. It is quite a bit faster than DES, and much +faster than IDEA or RC2. + +Blowfish consists of a key setup phase and the actual encryption or decryption +phase. + +BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key +at B<data>. + +BF_ecb_encrypt() is the basic Blowfish encryption and decryption function. +It encrypts or decrypts the first 64 bits of B<in> using the key B<key>, +putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>) +or decryption (B<BF_DECRYPT>) shall be performed. The vector pointed at by +B<in> and B<out> must be 64 bits in length, no less. If they are larger, +everything after the first 64 bits is ignored. + +The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt() +all operate on variable length data. They all take an initialization vector +B<ivec> which needs to be passed along into the next call of the same function +for the same message. B<ivec> may be initialized with anything, but the +recipient needs to know what it was initialized with, or it won't be able +to decrypt. Some programs and protocols simplify this, like SSH, where +B<ivec> is simply initialized to zero. +BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while +BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable +number of bytes (the amount does not have to be an exact multiple of 8). The +purpose of the latter two is to simulate stream ciphers, and therefore, they +need the parameter B<num>, which is a pointer to an integer where the current +offset in B<ivec> is stored between calls. This integer must be initialized +to zero when B<ivec> is initialized. + +BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It +encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>, +putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or +decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte +long initialization vector. + +BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback. +It encrypts or decrypts the bytes in B<in> using the key B<schedule>, +putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>) +or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an +8 byte long initialization vector. B<num> must point at an integer which must +be initially zero. + +BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback. +It uses the same parameters as BF_cfb64_encrypt(), which must be initialized +the same way. + +BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish +encryption. They encrypt/decrypt the first 64 bits of the vector pointed by +B<data>, using the key B<key>. These functions should not be used unless you +implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt(). +If you still want to use these functions, you should be aware that they take +each 32-bit chunk in host-byte order, which is little-endian on little-endian +platforms and big-endian on big-endian ones. + +=head1 RETURN VALUES + +None of the functions presented here return any value. + +=head1 NOTE + +Applications should use the higher level functions +L<EVP_EncryptInit(3)> etc. instead of calling these +functions directly. + +=head1 SEE ALSO + +L<EVP_EncryptInit(3)>, +L<des_modes(7)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_ADDR.pod b/openssl-1.1.0h/doc/crypto/BIO_ADDR.pod new file mode 100644 index 0000000..4b169e8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_ADDR.pod @@ -0,0 +1,125 @@ +=pod + +=head1 NAME + +BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake, +BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, +BIO_ADDR_hostname_string, BIO_ADDR_service_string, +BIO_ADDR_path_string - BIO_ADDR routines + +=head1 SYNOPSIS + + #include <sys/types.h> + #include <openssl/bio.h> + + typedef union bio_addr_st BIO_ADDR; + + BIO_ADDR *BIO_ADDR_new(void); + void BIO_ADDR_free(BIO_ADDR *); + void BIO_ADDR_clear(BIO_ADDR *ap); + int BIO_ADDR_rawmake(BIO_ADDR *ap, int family, + const void *where, size_t wherelen, unsigned short port); + int BIO_ADDR_family(const BIO_ADDR *ap); + int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l); + unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap); + char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric); + char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric); + char *BIO_ADDR_path_string(const BIO_ADDR *ap); + +=head1 DESCRIPTION + +The B<BIO_ADDR> type is a wrapper around all types of socket +addresses that OpenSSL deals with, currently transparently +supporting AF_INET, AF_INET6 and AF_UNIX according to what's +available on the platform at hand. + +BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used +with routines that will fill it with information, such as +BIO_accept_ex(). + +BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new(). + +BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets +it back to an uninitialised state. + +BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of +size B<wherelen> with an address in network byte order pointed at +by B<where> and a port number in network byte order in B<port> (except +for the B<AF_UNIX> protocol family, where B<port> is meaningless and +therefore ignored) and populates the given B<BIO_ADDR> with them. +In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected +to be the length of the path string (not including the terminating +NUL, such as the result of a call to strlen()). +I<Read on about the addresses in L</RAW ADDRESSES> below>. + +BIO_ADDR_family() returns the protocol family of the given +B<BIO_ADDR>. The possible non-error results are one of the +constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the +BIO_ADDR has not been initialised. + +BIO_ADDR_rawaddress() will write the raw address of the given +B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL, +and will set B<*l> to be the amount of bytes the raw address +takes up if B<l> is non-NULL. +A technique to only find out the size of the address is a call +with B<p> set to B<NULL>. The raw address will be in network byte +order, most significant byte first. +In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the +path string (not including the terminating NUL, such as the result of +a call to strlen()). +I<Read on about the addresses in L</RAW ADDRESSES> below>. + +BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>. +The raw port will be in network byte order. + +BIO_ADDR_hostname_string() returns a character string with the +hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string +will contain the numerical form of the address. This only works for +B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The +returned string has been allocated on the heap and must be freed +with OPENSSL_free(). + +BIO_ADDR_service_string() returns a character string with the +service name of the port of the given B<BIO_ADDR>. If B<numeric> +is 1, the string will contain the port number. This only works +for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The +returned string has been allocated on the heap and must be freed +with OPENSSL_free(). + +BIO_ADDR_path_string() returns a character string with the path +of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the +protocol family AF_UNIX. The returned string has been allocated +on the heap and must be freed with OPENSSL_free(). + +=head1 RAW ADDRESSES + +Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a +network byte order address of a specific site. Internally, those are +treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct +in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all +depending on the protocol family the address is for. + +=head1 RETURN VALUES + +The string producing functions BIO_ADDR_hostname_string(), +BIO_ADDR_service_string() and BIO_ADDR_path_string() will +return B<NULL> on error and leave an error indication on the +OpenSSL error stack. + +All other functions described here return 0 or B<NULL> when the +information they should return isn't available. + +=head1 SEE ALSO + +L<BIO_connect(3)>, L<BIO_s_connect(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_ADDRINFO.pod b/openssl-1.1.0h/doc/crypto/BIO_ADDRINFO.pod new file mode 100644 index 0000000..7811da4 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_ADDRINFO.pod @@ -0,0 +1,91 @@ +=pod + +=head1 NAME + +BIO_lookup_type, +BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free, +BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol, +BIO_ADDRINFO_address, +BIO_lookup +- BIO_ADDRINFO type and routines + +=head1 SYNOPSIS + + #include <sys/types.h> + #include <openssl/bio.h> + + typedef union bio_addrinfo_st BIO_ADDRINFO; + + enum BIO_lookup_type { + BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER + }; + int BIO_lookup(const char *node, const char *service, + enum BIO_lookup_type lookup_type, + int family, int socktype, BIO_ADDRINFO **res); + + const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai); + int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai); + int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai); + int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai); + const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai); + void BIO_ADDRINFO_free(BIO_ADDRINFO *bai); + +=head1 DESCRIPTION + +The B<BIO_ADDRINFO> type is a wrapper for address information +types provided on your platform. + +B<BIO_ADDRINFO> normally forms a chain of several that can be +picked at one by one. + +BIO_lookup() looks up a specified B<host> and B<service>, and +uses B<lookup_type> to determine what the default address should +be if B<host> is B<NULL>. B<family>, B<socktype> are used to +determine what protocol family and protocol should be used for +the lookup. B<family> can be any of AF_INET, AF_INET6, AF_UNIX and +AF_UNSPEC, and B<socktype> can be SOCK_STREAM or SOCK_DGRAM. +B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO> +chain. +For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service> +parameter and expects the B<node> parameter to hold the path to the +socket file. + +BIO_ADDRINFO_family() returns the family of the given +B<BIO_ADDRINFO>. The result will be one of the constants +AF_INET, AF_INET6 and AF_UNIX. + +BIO_ADDRINFO_socktype() returns the socket type of the given +B<BIO_ADDRINFO>. The result will be one of the constants +SOCK_STREAM and SOCK_DGRAM. + +BIO_ADDRINFO_protocol() returns the protocol id of the given +B<BIO_ADDRINFO>. The result will be one of the constants +IPPROTO_TCP and IPPROTO_UDP. + +BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR> +of the given B<BIO_ADDRINFO>. + +BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain +from the given one. + +BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting +with the given one. + +=head1 RETURN VALUES + +BIO_lookup() returns 1 on success and 0 when an error occurred, and +will leave an error indication on the OpenSSL error stack in that case. + +All other functions described here return 0 or B<NULL> when the +information they should return isn't available. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_connect.pod b/openssl-1.1.0h/doc/crypto/BIO_connect.pod new file mode 100644 index 0000000..5194033 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_connect.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO +socket communication setup routines + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_socket(int domain, int socktype, int protocol, int options); + int BIO_connect(int sock, const BIO_ADDR *addr, int options); + int BIO_listen(int sock, const BIO_ADDR *addr, int options); + int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options); + int BIO_closesocket(int sock); + +=head1 DESCRIPTION + +BIO_socket() creates a socket in the domain B<domain>, of type +B<socktype> and B<protocol>. Socket B<options> are currently unused, +but is present for future use. + +BIO_connect() connects B<sock> to the address and service given by +B<addr>. Connection B<options> may be zero or any combination of +B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>. +The flags are described in L</FLAGS> below. + +BIO_listen() has B<sock> start listening on the address and service +given by B<addr>. Connection B<options> may be zero or any +combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>, +B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>. +The flags are described in L</FLAGS> below. + +BIO_accept_ex() waits for an incoming connections on the given +socket B<accept_sock>. When it gets a connection, the address and +port of the peer gets stored in B<peer> if that one is non-NULL. +Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied +on the accepted socket. The flags are described in L</FLAGS> below. + +BIO_closesocket() closes B<sock>. + +=head1 FLAGS + +=over 4 + +=item BIO_SOCK_KEEPALIVE + +Enables regular sending of keep-alive messages. + +=item BIO_SOCK_NONBLOCK + +Sets the socket to non-blocking mode. + +=item BIO_SOCK_NODELAY + +Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With +this set, any data will be sent as soon as possible instead of being +buffered until there's enough for the socket to send out in one go. + +=item BIO_SOCK_REUSEADDR + +Try to reuse the address and port combination for a recently closed +port. + +=item BIO_SOCK_V6_ONLY + +When creating an IPv6 socket, make it only listen for IPv6 addresses +and not IPv4 addresses mapped to IPv6. + +=back + +These flags are bit flags, so they are to be combined with the +C<|> operator, for example: + + BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK); + +=head1 RETURN VALUES + +BIO_socket() returns the socket number on success or B<INVALID_SOCKET> +(-1) on error. When an error has occurred, the OpenSSL error stack +will hold the error data and errno has the system error. + +BIO_connect() and BIO_listen() return 1 on success or 0 on error. +When an error has occurred, the OpenSSL error stack will hold the error +data and errno has the system error. + +BIO_accept_ex() returns the accepted socket on success or +B<INVALID_SOCKET> (-1) on error. When an error has occurred, the +OpenSSL error stack will hold the error data and errno has the system +error. + +=head1 HISTORY + +BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(), +BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL +1.1. Use the functions described above instead. + +=head1 SEE ALSO + +L<BIO_ADDR(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_ctrl.pod b/openssl-1.1.0h/doc/crypto/BIO_ctrl.pod new file mode 100644 index 0000000..60cd108 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_ctrl.pod @@ -0,0 +1,136 @@ +=pod + +=head1 NAME + +BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, +BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, +BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, +BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb +- BIO control operations + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + typedef int BIO_info_cb(BIO *b, int state, int res); + + long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg); + long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb); + char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg); + long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg); + + int BIO_reset(BIO *b); + int BIO_seek(BIO *b, int ofs); + int BIO_tell(BIO *b); + int BIO_flush(BIO *b); + int BIO_eof(BIO *b); + int BIO_set_close(BIO *b, long flag); + int BIO_get_close(BIO *b); + int BIO_pending(BIO *b); + int BIO_wpending(BIO *b); + size_t BIO_ctrl_pending(BIO *b); + size_t BIO_ctrl_wpending(BIO *b); + + int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp); + int BIO_set_info_callback(BIO *b, BIO_info_cb *cb); + +=head1 DESCRIPTION + +BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() +are BIO "control" operations taking arguments of various types. +These functions are not normally called directly, various macros +are used instead. The standard macros are described below, macros +specific to a particular type of BIO are described in the specific +BIOs manual page as well as any special features of the standard +calls. + +BIO_reset() typically resets a BIO to some initial state, in the case +of file related BIOs for example it rewinds the file pointer to the +start of the file. + +BIO_seek() resets a file related BIO's (that is file descriptor and +FILE BIOs) file position pointer to B<ofs> bytes from start of file. + +BIO_tell() returns the current file position of a file related BIO. + +BIO_flush() normally writes out any internally buffered data, in some +cases it is used to signal EOF and that no more data will be written. + +BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of +"EOF" varies according to the BIO type. + +BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can +take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used +in a source/sink BIO to indicate that the underlying I/O stream should +be closed when the BIO is freed. + +BIO_get_close() returns the BIOs close flag. + +BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() +return the number of pending characters in the BIOs read and write buffers. +Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() +return a size_t type and are functions, BIO_pending() and BIO_wpending() are +macros which call BIO_ctrl(). + +=head1 RETURN VALUES + +BIO_reset() normally returns 1 for success and 0 or -1 for failure. File +BIOs are an exception, they return 0 for success and -1 for failure. + +BIO_seek() and BIO_tell() both return the current file position on success +and -1 for failure, except file BIOs which for BIO_seek() always return 0 +for success and -1 for failure. + +BIO_flush() returns 1 for success and 0 or -1 for failure. + +BIO_eof() returns 1 if EOF has been reached 0 otherwise. + +BIO_set_close() always returns 1. + +BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. + +BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() +return the amount of pending data. + +=head1 NOTES + +BIO_flush(), because it can write data may return 0 or -1 indicating +that the call should be retried later in a similar manner to BIO_write_ex(). +The BIO_should_retry() call should be used and appropriate action taken +is the call fails. + +The return values of BIO_pending() and BIO_wpending() may not reliably +determine the amount of pending data in all cases. For example in the +case of a file BIO some data may be available in the FILE structures +internal buffers but it is not possible to determine this in a +portably way. For other types of BIO they may not be supported. + +Filter BIOs if they do not internally handle a particular BIO_ctrl() +operation usually pass the operation to the next BIO in the chain. +This often means there is no need to locate the required BIO for +a particular operation, it can be called on a chain and it will +be automatically passed to the relevant BIO. However this can cause +unexpected results: for example no current filter BIOs implement +BIO_seek(), but this may still succeed if the chain ends in a FILE +or file descriptor BIO. + +Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl() +operation. + +=head1 BUGS + +Some of the return values are ambiguous and care should be taken. In +particular a return value of 0 can be returned if an operation is not +supported, if an error occurred, if EOF has not been reached and in +the case of BIO_seek() on a file BIO for a successful operation. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_f_base64.pod b/openssl-1.1.0h/doc/crypto/BIO_f_base64.pod new file mode 100644 index 0000000..19df1dd --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_f_base64.pod @@ -0,0 +1,91 @@ +=pod + +=head1 NAME + +BIO_f_base64 - base64 BIO filter + +=for comment multiple includes + +=head1 SYNOPSIS + + #include <openssl/bio.h> + #include <openssl/evp.h> + + const BIO_METHOD *BIO_f_base64(void); + +=head1 DESCRIPTION + +BIO_f_base64() returns the base64 BIO method. This is a filter +BIO that base64 encodes any data written through it and decodes +any data read through it. + +Base64 BIOs do not support BIO_gets() or BIO_puts(). + +BIO_flush() on a base64 BIO that is being written through is +used to signal that no more data is to be encoded: this is used +to flush the final block through the BIO. + +The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags() +to encode the data all on one line or expect the data to be all +on one line. + +=head1 NOTES + +Because of the format of base64 encoding the end of the encoded +block cannot always be reliably determined. + +=head1 RETURN VALUES + +BIO_f_base64() returns the base64 BIO method. + +=head1 EXAMPLES + +Base64 encode the string "Hello World\n" and write the result +to standard output: + + BIO *bio, *b64; + char message[] = "Hello World \n"; + + b64 = BIO_new(BIO_f_base64()); + bio = BIO_new_fp(stdout, BIO_NOCLOSE); + BIO_push(b64, bio); + BIO_write(b64, message, strlen(message)); + BIO_flush(b64); + + BIO_free_all(b64); + +Read Base64 encoded data from standard input and write the decoded +data to standard output: + + BIO *bio, *b64, *bio_out; + char inbuf[512]; + int inlen; + + b64 = BIO_new(BIO_f_base64()); + bio = BIO_new_fp(stdin, BIO_NOCLOSE); + bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); + BIO_push(b64, bio); + while((inlen = BIO_read(b64, inbuf, 512)) > 0) + BIO_write(bio_out, inbuf, inlen); + + BIO_flush(bio_out); + BIO_free_all(b64); + +=head1 BUGS + +The ambiguity of EOF in base64 encoded data can cause additional +data following the base64 encoded block to be misinterpreted. + +There should be some way of specifying a test that the BIO can perform +to reliably determine EOF (for example a MIME boundary). + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_f_buffer.pod b/openssl-1.1.0h/doc/crypto/BIO_f_buffer.pod new file mode 100644 index 0000000..3224710 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_f_buffer.pod @@ -0,0 +1,92 @@ +=pod + +=head1 NAME + +BIO_get_buffer_num_lines, +BIO_set_read_buffer_size, +BIO_set_write_buffer_size, +BIO_set_buffer_size, +BIO_set_buffer_read_data, +BIO_f_buffer +- buffering BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD *BIO_f_buffer(void); + + long BIO_get_buffer_num_lines(BIO *b); + long BIO_set_read_buffer_size(BIO *b, long size); + long BIO_set_write_buffer_size(BIO *b, long size); + long BIO_set_buffer_size(BIO *b, long size); + long BIO_set_buffer_read_data(BIO *b, void *buf, long num); + +=head1 DESCRIPTION + +BIO_f_buffer() returns the buffering BIO method. + +Data written to a buffering BIO is buffered and periodically written +to the next BIO in the chain. Data read from a buffering BIO comes from +an internal buffer which is filled from the next BIO in the chain. +Both BIO_gets() and BIO_puts() are supported. + +Calling BIO_reset() on a buffering BIO clears any buffered data. + +BIO_get_buffer_num_lines() returns the number of lines currently buffered. + +BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() +set the read, write or both read and write buffer sizes to B<size>. The initial +buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the +buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared +when the buffer is resized. + +BIO_set_buffer_read_data() clears the read buffer and fills it with B<num> +bytes of B<buf>. If B<num> is larger than the current buffer size the buffer +is expanded. + +=head1 NOTES + +These functions, other than BIO_f_buffer(), are implemented as macros. + +Buffering BIOs implement BIO_gets() by using BIO_read() operations on the +next BIO in the chain. By prepending a buffering BIO to a chain it is therefore +possible to provide BIO_gets() functionality if the following BIOs do not +support it (for example SSL BIOs). + +Data is only written to the next BIO in the chain when the write buffer fills +or when BIO_flush() is called. It is therefore important to call BIO_flush() +whenever any pending data should be written such as when removing a buffering +BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate +source/sink BIO is non blocking. + +=head1 RETURN VALUES + +BIO_f_buffer() returns the buffering BIO method. + +BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0). + +BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() +return 1 if the buffer was successfully resized or 0 for failure. + +BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if +there was an error. + +=head1 SEE ALSO + +L<BIO(3)>, +L<BIO_reset(3)>, +L<BIO_flush(3)>, +L<BIO_pop(3)>, +L<BIO_ctrl(3)>. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_f_cipher.pod b/openssl-1.1.0h/doc/crypto/BIO_f_cipher.pod new file mode 100644 index 0000000..87ab3cc --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_f_cipher.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter + +=for comment multiple includes + +=head1 SYNOPSIS + + #include <openssl/bio.h> + #include <openssl/evp.h> + + const BIO_METHOD *BIO_f_cipher(void); + void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher, + unsigned char *key, unsigned char *iv, int enc); + int BIO_get_cipher_status(BIO *b) + int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx) + +=head1 DESCRIPTION + +BIO_f_cipher() returns the cipher BIO method. This is a filter +BIO that encrypts any data written through it, and decrypts any data +read from it. It is a BIO wrapper for the cipher routines +EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal(). + +Cipher BIOs do not support BIO_gets() or BIO_puts(). + +BIO_flush() on an encryption BIO that is being written through is +used to signal that no more data is to be encrypted: this is used +to flush and possibly pad the final block through the BIO. + +BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key> +and IV B<iv>. B<enc> should be set to 1 for encryption and zero for +decryption. + +When reading from an encryption BIO the final block is automatically +decrypted and checked when EOF is detected. BIO_get_cipher_status() +is a BIO_ctrl() macro which can be called to determine whether the +decryption operation was successful. + +BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal +BIO cipher context. The retrieved context can be used in conjunction +with the standard cipher routines to set it up. This is useful when +BIO_set_cipher() is not flexible enough for the applications needs. + +=head1 NOTES + +When encrypting BIO_flush() B<must> be called to flush the final block +through the BIO. If it is not then the final block will fail a subsequent +decrypt. + +When decrypting an error on the final block is signaled by a zero +return value from the read operation. A successful decrypt followed +by EOF will also return zero for the final read. BIO_get_cipher_status() +should be called to determine if the decrypt was successful. + +As always, if BIO_gets() or BIO_puts() support is needed then it can +be achieved by preceding the cipher BIO with a buffering BIO. + +=head1 RETURN VALUES + +BIO_f_cipher() returns the cipher BIO method. + +BIO_set_cipher() does not return a value. + +BIO_get_cipher_status() returns 1 for a successful decrypt and 0 +for failure. + +BIO_get_cipher_ctx() currently always returns 1. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_f_md.pod b/openssl-1.1.0h/doc/crypto/BIO_f_md.pod new file mode 100644 index 0000000..32f0046 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_f_md.pod @@ -0,0 +1,156 @@ +=pod + +=head1 NAME + +BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter + +=for comment multiple includes + +=head1 SYNOPSIS + + #include <openssl/bio.h> + #include <openssl/evp.h> + + const BIO_METHOD *BIO_f_md(void); + int BIO_set_md(BIO *b, EVP_MD *md); + int BIO_get_md(BIO *b, EVP_MD **mdp); + int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp); + +=head1 DESCRIPTION + +BIO_f_md() returns the message digest BIO method. This is a filter +BIO that digests any data passed through it, it is a BIO wrapper +for the digest routines EVP_DigestInit(), EVP_DigestUpdate() +and EVP_DigestFinal(). + +Any data written or read through a digest BIO using BIO_read() and +BIO_write() is digested. + +BIO_gets(), if its B<size> parameter is large enough finishes the +digest calculation and returns the digest value. BIO_puts() is +not supported. + +BIO_reset() reinitialises a digest BIO. + +BIO_set_md() sets the message digest of BIO B<b> to B<md>: this +must be called to initialize a digest BIO before any data is +passed through it. It is a BIO_ctrl() macro. + +BIO_get_md() places the a pointer to the digest BIOs digest method +in B<mdp>, it is a BIO_ctrl() macro. + +BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>. + +=head1 NOTES + +The context returned by BIO_get_md_ctx() can be used in calls +to EVP_DigestFinal() and also the signature routines EVP_SignFinal() +and EVP_VerifyFinal(). + +The context returned by BIO_get_md_ctx() is an internal context +structure. Changes made to this context will affect the digest +BIO itself and the context pointer will become invalid when the digest +BIO is freed. + +After the digest has been retrieved from a digest BIO it must be +reinitialized by calling BIO_reset(), or BIO_set_md() before any more +data is passed through it. + +If an application needs to call BIO_gets() or BIO_puts() through +a chain containing digest BIOs then this can be done by prepending +a buffering BIO. + +Calling BIO_get_md_ctx() will return the context and initialize the BIO +state. This allows applications to initialize the context externally +if the standard calls such as BIO_set_md() are not sufficiently flexible. + +=head1 RETURN VALUES + +BIO_f_md() returns the digest BIO method. + +BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and +0 for failure. + +=head1 EXAMPLES + +The following example creates a BIO chain containing an SHA1 and MD5 +digest BIO and passes the string "Hello World" through it. Error +checking has been omitted for clarity. + + BIO *bio, *mdtmp; + char message[] = "Hello World"; + bio = BIO_new(BIO_s_null()); + mdtmp = BIO_new(BIO_f_md()); + BIO_set_md(mdtmp, EVP_sha1()); + /* For BIO_push() we want to append the sink BIO and keep a note of + * the start of the chain. + */ + bio = BIO_push(mdtmp, bio); + mdtmp = BIO_new(BIO_f_md()); + BIO_set_md(mdtmp, EVP_md5()); + bio = BIO_push(mdtmp, bio); + /* Note: mdtmp can now be discarded */ + BIO_write(bio, message, strlen(message)); + +The next example digests data by reading through a chain instead: + + BIO *bio, *mdtmp; + char buf[1024]; + int rdlen; + bio = BIO_new_file(file, "rb"); + mdtmp = BIO_new(BIO_f_md()); + BIO_set_md(mdtmp, EVP_sha1()); + bio = BIO_push(mdtmp, bio); + mdtmp = BIO_new(BIO_f_md()); + BIO_set_md(mdtmp, EVP_md5()); + bio = BIO_push(mdtmp, bio); + do { + rdlen = BIO_read(bio, buf, sizeof(buf)); + /* Might want to do something with the data here */ + } while (rdlen > 0); + +This next example retrieves the message digests from a BIO chain and +outputs them. This could be used with the examples above. + + BIO *mdtmp; + unsigned char mdbuf[EVP_MAX_MD_SIZE]; + int mdlen; + int i; + mdtmp = bio; /* Assume bio has previously been set up */ + do { + EVP_MD *md; + mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD); + if (!mdtmp) break; + BIO_get_md(mdtmp, &md); + printf("%s digest", OBJ_nid2sn(EVP_MD_type(md))); + mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE); + for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]); + printf("\n"); + mdtmp = BIO_next(mdtmp); + } while (mdtmp); + + BIO_free_all(bio); + +=head1 BUGS + +The lack of support for BIO_puts() and the non standard behaviour of +BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets() +and BIO_puts() should be passed to the next BIO in the chain and digest +the data passed through and that digests should be retrieved using a +separate BIO_ctrl() call. + +=head1 HISTORY + +Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the +BIO was initialized first. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_f_null.pod b/openssl-1.1.0h/doc/crypto/BIO_f_null.pod new file mode 100644 index 0000000..c4e4c66 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_f_null.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +BIO_f_null - null filter + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD * BIO_f_null(void); + +=head1 DESCRIPTION + +BIO_f_null() returns the null filter BIO method. This is a filter BIO +that does nothing. + +All requests to a null filter BIO are passed through to the next BIO in +the chain: this means that a BIO chain containing a null filter BIO +behaves just as though the BIO was not there. + +=head1 NOTES + +As may be apparent a null filter BIO is not particularly useful. + +=head1 RETURN VALUES + +BIO_f_null() returns the null filter BIO method. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_f_ssl.pod b/openssl-1.1.0h/doc/crypto/BIO_f_ssl.pod new file mode 100644 index 0000000..3f9635e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_f_ssl.pod @@ -0,0 +1,298 @@ +=pod + +=head1 NAME + +BIO_do_handshake, +BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, +BIO_set_ssl_renegotiate_bytes, +BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, +BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, +BIO_ssl_shutdown - SSL BIO + +=for comment multiple includes + +=head1 SYNOPSIS + + #include <openssl/bio.h> + #include <openssl/ssl.h> + + const BIO_METHOD *BIO_f_ssl(void); + + long BIO_set_ssl(BIO *b, SSL *ssl, long c); + long BIO_get_ssl(BIO *b, SSL **sslp); + long BIO_set_ssl_mode(BIO *b, long client); + long BIO_set_ssl_renegotiate_bytes(BIO *b, long num); + long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds); + long BIO_get_num_renegotiates(BIO *b); + + BIO *BIO_new_ssl(SSL_CTX *ctx, int client); + BIO *BIO_new_ssl_connect(SSL_CTX *ctx); + BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); + int BIO_ssl_copy_session_id(BIO *to, BIO *from); + void BIO_ssl_shutdown(BIO *bio); + + long BIO_do_handshake(BIO *b); + +=head1 DESCRIPTION + +BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which +is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to +SSL I/O. + +I/O performed on an SSL BIO communicates using the SSL protocol with +the SSLs read and write BIOs. If an SSL connection is not established +then an attempt is made to establish one on the first I/O call. + +If a BIO is appended to an SSL BIO using BIO_push() it is automatically +used as the SSL BIOs read and write BIOs. + +Calling BIO_reset() on an SSL BIO closes down any current SSL connection +by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in +the chain: this will typically disconnect the underlying transport. +The SSL BIO is then reset to the initial accept or connect state. + +If the close flag is set when an SSL BIO is freed then the internal +SSL structure is also freed using SSL_free(). + +BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using +the close flag B<c>. + +BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be +manipulated using the standard SSL library functions. + +BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> +is 1 client mode is set. If B<client> is 0 server mode is set. + +BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count +to B<num>. When set after every B<num> bytes of I/O (read and write) +the SSL session is automatically renegotiated. B<num> must be at +least 512 bytes. + +BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to +B<seconds>. When the renegotiate timeout elapses the session is +automatically renegotiated. + +BIO_get_num_renegotiates() returns the total number of session +renegotiations due to I/O or timeout. + +BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using +client mode if B<client> is non zero. + +BIO_new_ssl_connect() creates a new BIO chain consisting of an +SSL BIO (using B<ctx>) followed by a connect BIO. + +BIO_new_buffer_ssl_connect() creates a new BIO chain consisting +of a buffering BIO, an SSL BIO (using B<ctx>) and a connect +BIO. + +BIO_ssl_copy_session_id() copies an SSL session id between +BIO chains B<from> and B<to>. It does this by locating the +SSL BIOs in each chain and calling SSL_copy_session_id() on +the internal SSL pointer. + +BIO_ssl_shutdown() closes down an SSL connection on BIO +chain B<bio>. It does this by locating the SSL BIO in the +chain and calling SSL_shutdown() on its internal SSL +pointer. + +BIO_do_handshake() attempts to complete an SSL handshake on the +supplied BIO and establish the SSL connection. It returns 1 +if the connection was established successfully. A zero or negative +value is returned if the connection could not be established, the +call BIO_should_retry() should be used for non blocking connect BIOs +to determine if the call should be retried. If an SSL connection has +already been established this call has no effect. + +=head1 NOTES + +SSL BIOs are exceptional in that if the underlying transport +is non blocking they can still request a retry in exceptional +circumstances. Specifically this will happen if a session +renegotiation takes place during a BIO_read() operation, one +case where this happens is when step up occurs. + +The SSL flag SSL_AUTO_RETRY can be +set to disable this behaviour. That is when this flag is set +an SSL BIO using a blocking transport will never request a +retry. + +Since unknown BIO_ctrl() operations are sent through filter +BIOs the servers name and port can be set using BIO_set_host() +on the BIO returned by BIO_new_ssl_connect() without having +to locate the connect BIO first. + +Applications do not have to call BIO_do_handshake() but may wish +to do so to separate the handshake process from other I/O +processing. + +BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), +BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), +BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros. + +=head1 EXAMPLE + +This SSL/TLS client example, attempts to retrieve a page from an +SSL/TLS web server. The I/O routines are identical to those of the +unencrypted example in L<BIO_s_connect(3)>. + + BIO *sbio, *out; + int len; + char tmpbuf[1024]; + SSL_CTX *ctx; + SSL *ssl; + + /* XXX Seed the PRNG if needed. */ + + ctx = SSL_CTX_new(TLS_client_method()); + + /* XXX Set verify paths and mode here. */ + + sbio = BIO_new_ssl_connect(ctx); + BIO_get_ssl(sbio, &ssl); + if (ssl == NULL) { + fprintf(stderr, "Can't locate SSL pointer\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + + /* Don't want any retries */ + SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + + /* XXX We might want to do other things with ssl here */ + + /* An empty host part means the loopback address */ + BIO_set_conn_hostname(sbio, ":https"); + + out = BIO_new_fp(stdout, BIO_NOCLOSE); + if (BIO_do_connect(sbio) <= 0) { + fprintf(stderr, "Error connecting to server\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + if (BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error establishing SSL connection\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + + /* XXX Could examine ssl here to get connection info */ + + BIO_puts(sbio, "GET / HTTP/1.0\n\n"); + for ( ; ; ) { + len = BIO_read(sbio, tmpbuf, 1024); + if (len <= 0) + break; + BIO_write(out, tmpbuf, len); + } + BIO_free_all(sbio); + BIO_free(out); + +Here is a simple server example. It makes use of a buffering +BIO to allow lines to be read from the SSL BIO using BIO_gets. +It creates a pseudo web page containing the actual request from +a client and also echoes the request to standard output. + + BIO *sbio, *bbio, *acpt, *out; + int len; + char tmpbuf[1024]; + SSL_CTX *ctx; + SSL *ssl; + + /* XXX Seed the PRNG if needed. */ + + ctx = SSL_CTX_new(TLS_server_method()); + if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM) + || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM) + || !SSL_CTX_check_private_key(ctx)) { + fprintf(stderr, "Error setting up SSL_CTX\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + + /* XXX Other things like set verify locations, EDH temp callbacks. */ + + /* New SSL BIO setup as server */ + sbio = BIO_new_ssl(ctx, 0); + BIO_get_ssl(sbio, &ssl); + if (ssl == NULL) { + fprintf(stderr, "Can't locate SSL pointer\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + + SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + bbio = BIO_new(BIO_f_buffer()); + sbio = BIO_push(bbio, sbio); + acpt = BIO_new_accept("4433"); + + /* + * By doing this when a new connection is established + * we automatically have sbio inserted into it. The + * BIO chain is now 'swallowed' by the accept BIO and + * will be freed when the accept BIO is freed. + */ + BIO_set_accept_bios(acpt, sbio); + out = BIO_new_fp(stdout, BIO_NOCLOSE); + + /* Setup accept BIO */ + if (BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error setting up accept BIO\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + + if (BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error in connection\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + + /* We only want one connection so remove and free accept BIO */ + sbio = BIO_pop(acpt); + BIO_free_all(acpt); + + if (BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error in SSL handshake\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + + BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); + BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); + BIO_puts(sbio, "--------------------------------------------------\r\n"); + + for ( ; ; ) { + len = BIO_gets(sbio, tmpbuf, 1024); + if (len <= 0) + break; + BIO_write(sbio, tmpbuf, len); + BIO_write(out, tmpbuf, len); + /* Look for blank line signifying end of headers*/ + if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n') + break; + } + + BIO_puts(sbio, "--------------------------------------------------\r\n"); + BIO_puts(sbio, "\r\n"); + BIO_flush(sbio); + BIO_free_all(sbio); + +=head1 BUGS + +In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly, +the I/O BIO reference count was incorrectly incremented (instead of +decremented) and dissociated with the SSL BIO even if the SSL BIO was not +explicitly being popped (e.g. a pop higher up the chain). Applications which +included workarounds for this bug (e.g. freeing BIOs more than once) should +be modified to handle this fix or they may free up an already freed BIO. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_find_type.pod b/openssl-1.1.0h/doc/crypto/BIO_find_type.pod new file mode 100644 index 0000000..ff7b488 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_find_type.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO *BIO_find_type(BIO *b, int bio_type); + BIO *BIO_next(BIO *b); + int BIO_method_type(const BIO *b); + +=head1 DESCRIPTION + +The BIO_find_type() searches for a BIO of a given type in a chain, starting +at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search +is made for a BIO of that type. If B<type> is a general type (such as +B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is +searched for. BIO_find_type() returns the next matching BIO or NULL if none is +found. + +The following general types are defined: +B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>. + +For a list of the specific types, see the B<openssl/bio.h> header file. + +BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs +in a chain or used in conjunction with BIO_find_type() to find all BIOs of a +certain type. + +BIO_method_type() returns the type of a BIO. + +=head1 RETURN VALUES + +BIO_find_type() returns a matching BIO or NULL for no match. + +BIO_next() returns the next BIO in a chain. + +BIO_method_type() returns the type of the BIO B<b>. + +=head1 EXAMPLE + +Traverse a chain looking for digest BIOs: + + BIO *btmp; + btmp = in_bio; /* in_bio is chain to search through */ + + do { + btmp = BIO_find_type(btmp, BIO_TYPE_MD); + if (btmp == NULL) break; /* Not found */ + /* btmp is a digest BIO, do something with it ...*/ + ... + + btmp = BIO_next(btmp); + } while (btmp); + + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_get_data.pod b/openssl-1.1.0h/doc/crypto/BIO_get_data.pod new file mode 100644 index 0000000..c3137c4 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_get_data.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown, +BIO_get_shutdown - functions for managing BIO state information + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + void BIO_set_data(BIO *a, void *ptr); + void *BIO_get_data(BIO *a); + void BIO_set_init(BIO *a, int init); + int BIO_get_init(BIO *a); + void BIO_set_shutdown(BIO *a, int shut); + int BIO_get_shutdown(BIO *a); + +=head1 DESCRIPTION + +These functions are mainly useful when implementing a custom BIO. + +The BIO_set_data() function associates the custom data pointed to by B<ptr> with +the BIO. This data can subsequently be retrieved via a call to BIO_get_data(). +This can be used by custom BIOs for storing implementation specific information. + +The BIO_set_init() function sets the value of the BIO's "init" flag to indicate +whether initialisation has been completed for this BIO or not. A non-zero value +indicates that initialisation is complete, whilst zero indicates that it is not. +Often initialisation will complete during initial construction of the BIO. For +some BIOs however, initialisation may not complete until after additional steps +have occurred (for example through calling custom ctrls). The BIO_get_init() +function returns the value of the "init" flag. + +The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of +this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource +is also closed when the BIO is freed. + +=head1 RETURN VALUES + +BIO_get_data() returns a pointer to the implementation specific custom data +associated with this BIO, or NULL if none has been set. + +BIO_get_init() returns the state of the BIO's init flag. + +BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag. + +=head1 SEE ALSO + +L<bio>, L<BIO_meth_new> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_get_ex_new_index.pod b/openssl-1.1.0h/doc/crypto/BIO_get_ex_new_index.pod new file mode 100644 index 0000000..9cf20c2 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_get_ex_new_index.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data, +ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data, +UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data, +X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data, +X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data, +X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data, +DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data, +DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data, +ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data, +EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data, +RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data +- application-specific data + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int TYPE_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int TYPE_set_ex_data(TYPE *d, int idx, void *arg); + + void *TYPE_get_ex_data(TYPE *d, int idx); + +=head1 DESCRIPTION + +In the description here, I<TYPE> is used a placeholder +for any of the OpenSSL datatypes listed in +L<CRYPTO_get_ex_new_index(3)>. + +These functions handle application-specific data for OpenSSL data +structures. + +TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index() +with the correct B<index> value. + +TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with +an offset into the opaque exdata part of the TYPE object. + +TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an +an offset into the opaque exdata part of the TYPE object. + +=head1 SEE ALSO + +L<CRYPTO_get_ex_new_index(3)>. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_meth_new.pod b/openssl-1.1.0h/doc/crypto/BIO_meth_new.pod new file mode 100644 index 0000000..f682c37 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_meth_new.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +BIO_get_new_index, +BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write, +BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts, +BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl, +BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy, +BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, +BIO_meth_set_callback_ctrl - Routines to build up BIO methods + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_get_new_index(void); + BIO_METHOD *BIO_meth_new(int type, const char *name); + void BIO_meth_free(BIO_METHOD *biom); + int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int); + int BIO_meth_set_write(BIO_METHOD *biom, + int (*write) (BIO *, const char *, int)); + int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int); + int BIO_meth_set_read(BIO_METHOD *biom, + int (*read) (BIO *, char *, int)); + int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *); + int BIO_meth_set_puts(BIO_METHOD *biom, + int (*puts) (BIO *, const char *)); + int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int); + int BIO_meth_set_gets(BIO_METHOD *biom, + int (*gets) (BIO *, char *, int)); + long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *); + int BIO_meth_set_ctrl(BIO_METHOD *biom, + long (*ctrl) (BIO *, int, long, void *)); + int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *); + int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *)); + int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *); + int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *)); + long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom)) + (BIO *, int, BIO_info_cb *); + int BIO_meth_set_callback_ctrl(BIO_METHOD *biom, + long (*callback_ctrl) (BIO *, int, + BIO_info_cb *)); + +=head1 DESCRIPTION + +The B<BIO_METHOD> type is a structure used for the implementation of new BIO +types. It provides a set of of functions used by OpenSSL for the implementation +of the various BIO capabilities. See the L<bio> page for more information. + +BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a +unique integer B<type> and a string that represents its B<name>. +Use BIO_get_new_index() to get the value for B<type>. + +The set of +standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples +include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a +type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs +should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor +based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the +"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for +more information. + +BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory +associated with it. + +BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for +writing arbitrary length data to the BIO respectively. This function will be +called in response to the application calling BIO_write(). The parameters for +the function have the same meaning as for BIO_write(). + +BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for +reading arbitrary length data from the BIO respectively. This function will be +called in response to the application calling BIO_read(). The parameters for the +function have the same meaning as for BIO_read(). + +BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for +writing a NULL terminated string to the BIO respectively. This function will be +called in response to the application calling BIO_puts(). The parameters for +the function have the same meaning as for BIO_puts(). + +BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically +used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)> +page for more information). This function will be called in response to the +application calling BIO_gets(). The parameters for the function have the same +meaning as for BIO_gets(). + +BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for +processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for +more information. This function will be called in response to the application +calling BIO_ctrl(). The parameters for the function have the same meaning as for +BIO_ctrl(). + +BIO_meth_get_create() and BIO_meth_set_create() get and set the function used +for creating a new instance of the BIO respectively. This function will be +called in response to the application calling BIO_new() and passing +in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the +memory for the new BIO, and a pointer to this newly allocated structure will +be passed as a parameter to the function. + +BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used +for destroying an instance of a BIO respectively. This function will be +called in response to the application calling BIO_free(). A pointer to the BIO +to be destroyed is passed as a parameter. The destroy function should be used +for BIO specific clean up. The memory for the BIO itself should not be freed by +this function. + +BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the +function used for processing callback ctrl messages in the BIO respectively. See +the L<BIO_callback_ctrl(3)> page for more information. This function will be called +in response to the application calling BIO_callback_ctrl(). The parameters for +the function have the same meaning as for BIO_callback_ctrl(). + +=head1 SEE ALSO + +L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_new.pod b/openssl-1.1.0h/doc/crypto/BIO_new.pod new file mode 100644 index 0000000..006cf59 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_new.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all, +BIO_set - BIO allocation and freeing functions + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO * BIO_new(const BIO_METHOD *type); + int BIO_set(BIO *a, const BIO_METHOD *type); + int BIO_up_ref(BIO *a); + int BIO_free(BIO *a); + void BIO_vfree(BIO *a); + void BIO_free_all(BIO *a); + +=head1 DESCRIPTION + +The BIO_new() function returns a new BIO using method B<type>. + +BIO_up_ref() increments the reference count associated with the BIO object. + +BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO +but it does not return a value. +If B<a> is NULL nothing is done. +Calling BIO_free() may also have some effect +on the underlying I/O structure, for example it may close the file being +referred to under certain circumstances. For more details see the individual +BIO_METHOD descriptions. + +BIO_free_all() frees up an entire BIO chain, it does not halt if an error +occurs freeing up an individual BIO in the chain. +If B<a> is NULL nothing is done. + +=head1 RETURN VALUES + +BIO_new() returns a newly created BIO or NULL if the call fails. + +BIO_set(), BIO_up_ref() and BIO_free() return 1 for success and 0 for failure. + +BIO_free_all() and BIO_vfree() do not return values. + +=head1 NOTES + +If BIO_free() is called on a BIO chain it will only free one BIO resulting +in a memory leak. + +Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() +on it other than the discarded return value. + +=head1 HISTORY + +BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque. + +=head1 EXAMPLE + +Create a memory BIO: + + BIO *mem = BIO_new(BIO_s_mem()); + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_new_CMS.pod b/openssl-1.1.0h/doc/crypto/BIO_new_CMS.pod new file mode 100644 index 0000000..b06c224 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_new_CMS.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + +BIO_new_CMS - CMS streaming filter BIO + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output +of the filter is written to B<out>. Any data written to the chain is +automatically translated to a BER format CMS structure of the appropriate type. + +=head1 NOTES + +The chain returned by this function behaves like a standard filter BIO. It +supports non blocking I/O. Content is processed and streamed on the fly and not +all held in memory at once: so it is possible to encode very large structures. +After all content has been written through the chain BIO_flush() must be called +to finalise the structure. + +The B<CMS_STREAM> flag must be included in the corresponding B<flags> +parameter of the B<cms> creation function. + +If an application wishes to write additional data to B<out> BIOs should be +removed from the chain using BIO_pop() and freed with BIO_free() until B<out> +is reached. If no additional data needs to be written BIO_free_all() can be +called to free up the whole chain. + +Any content written through the filter is used verbatim: no canonical +translation is performed. + +It is possible to chain multiple BIOs to, for example, create a triple wrapped +signed, enveloped, signed structure. In this case it is the applications +responsibility to set the inner content type of any outer CMS_ContentInfo +structures. + +Large numbers of small writes through the chain should be avoided as this will +produce an output consisting of lots of OCTET STRING structures. Prepending +a BIO_f_buffer() buffering BIO will prevent this. + +=head1 BUGS + +There is currently no corresponding inverse BIO: i.e. one which can decode +a CMS structure on the fly. + +=head1 RETURN VALUES + +BIO_new_CMS() returns a BIO chain when successful or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_encrypt(3)> + +=head1 HISTORY + +BIO_new_CMS() was added to OpenSSL 1.0.0 + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_parse_hostserv.pod b/openssl-1.1.0h/doc/crypto/BIO_parse_hostserv.pod new file mode 100644 index 0000000..426e4de --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_parse_hostserv.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +BIO_hostserv_priorities, +BIO_parse_hostserv +- utility routines to parse a standard host and service string + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + enum BIO_hostserv_priorities { + BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV + }; + int BIO_parse_hostserv(const char *hostserv, char **host, char **service, + enum BIO_hostserv_priorities hostserv_prio); + +=head1 DESCRIPTION + +BIO_parse_hostserv() will parse the information given in B<hostserv>, +create strings with the host name and service name and give those +back via B<host> and B<service>. Those will need to be freed after +they are used. B<hostserv_prio> helps determine if B<hostserv> shall +be interpreted primarily as a host name or a service name in ambiguous +cases. + +The syntax the BIO_parse_hostserv() recognises is: + + host + ':' + service + host + ':' + '*' + host + ':' + ':' + service + '*' + ':' + service + host + service + +The host part can be a name or an IP address. If it's a IPv6 +address, it MUST be enclosed in brackets, such as '[::1]'. + +The service part can be a service name or its port number. + +The returned values will depend on the given B<hostserv> string +and B<hostserv_prio>, as follows: + + host + ':' + service => *host = "host", *service = "service" + host + ':' + '*' => *host = "host", *service = NULL + host + ':' => *host = "host", *service = NULL + ':' + service => *host = NULL, *service = "service" + '*' + ':' + service => *host = NULL, *service = "service" + + in case no ':' is present in the string, the result depends on + hostserv_prio, as follows: + + when hostserv_prio == BIO_PARSE_PRIO_HOST + host => *host = "host", *service untouched + + when hostserv_prio == BIO_PARSE_PRIO_SERV + service => *host untouched, *service = "service" + +=head1 SEE ALSO + +L<BIO_ADDRINFO(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_printf.pod b/openssl-1.1.0h/doc/crypto/BIO_printf.pod new file mode 100644 index 0000000..8045b64 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_printf.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf +- formatted output to a BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_printf(BIO *bio, const char *format, ...) + int BIO_vprintf(BIO *bio, const char *format, va_list args) + + int BIO_snprintf(char *buf, size_t n, const char *format, ...) + int BIO_vsnprintf(char *buf, size_t n, const char *format, va_list args) + +=head1 DESCRIPTION + +BIO_printf() is similar to the standard C printf() function, except that +the output is sent to the specified BIO, B<bio>, rather than standard +output. All common format specifiers are supported. + +BIO_vprintf() is similar to the vprintf() function found on many platforms, +the output is sent to the specified BIO, B<bio>, rather than standard +output. All common format specifiers are supported. The argument +list B<args> is a stdarg argument list. + +BIO_snprintf() is for platforms that do not have the common snprintf() +function. It is like sprintf() except that the size parameter, B<n>, +specifies the size of the output buffer. + +BIO_vsnprintf() is to BIO_snprintf() as BIO_vprintf() is to BIO_printf(). + +=head1 RETURN VALUES + +All functions return the number of bytes written, or -1 on error. +For BIO_snprintf() and BIO_vsnprintf() this includes when the output +buffer is too small. + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_push.pod b/openssl-1.1.0h/doc/crypto/BIO_push.pod new file mode 100644 index 0000000..ce56db9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_push.pod @@ -0,0 +1,89 @@ +=pod + +=head1 NAME + +BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO *BIO_push(BIO *b, BIO *append); + BIO *BIO_pop(BIO *b); + void BIO_set_next(BIO *b, BIO *next); + +=head1 DESCRIPTION + +The BIO_push() function appends the BIO B<append> to B<b>, it returns +B<b>. + +BIO_pop() removes the BIO B<b> from a chain and returns the next BIO +in the chain, or NULL if there is no next BIO. The removed BIO then +becomes a single BIO with no association with the original chain, +it can thus be freed or attached to a different chain. + +BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to +by B<next>. The new chain may include some of the same BIOs from the old chain +or it may be completely different. + +=head1 NOTES + +The names of these functions are perhaps a little misleading. BIO_push() +joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, +the deleted BIO does not need to be at the end of a chain. + +The process of calling BIO_push() and BIO_pop() on a BIO may have additional +consequences (a control call is made to the affected BIOs) any effects will +be noted in the descriptions of individual BIOs. + +=head1 EXAMPLES + +For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is +a base64 BIO and B<f> is a file BIO. + +If the call: + + BIO_push(b64, f); + +is made then the new chain will be B<b64-f>. After making the calls + + BIO_push(md2, b64); + BIO_push(md1, md2); + +the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested +by B<md1> and B<md2>, B<base64> encoded and written to B<f>. + +It should be noted that reading causes data to pass in the reverse +direction, that is data is read from B<f>, base64 B<decoded> and digested +by B<md1> and B<md2>. If the call: + + BIO_pop(md2); + +The call will return B<b64> and the new chain will be B<md1-b64-f> data can +be written to B<md1> as before. + +=head1 RETURN VALUES + +BIO_push() returns the end of the chain, B<b>. + +BIO_pop() returns the next BIO in the chain, or NULL if there is no next +BIO. + +=head1 SEE ALSO + +L<bio> + +=head1 HISTORY + +The BIO_set_next() function was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_read.pod b/openssl-1.1.0h/doc/crypto/BIO_read.pod new file mode 100644 index 0000000..45871c1 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_read.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_read(BIO *b, void *buf, int len); + int BIO_gets(BIO *b, char *buf, int size); + int BIO_write(BIO *b, const void *buf, int len); + int BIO_puts(BIO *b, const char *buf); + +=head1 DESCRIPTION + +BIO_read() attempts to read B<len> bytes from BIO B<b> and places +the data in B<buf>. + +BIO_gets() performs the BIOs "gets" operation and places the data +in B<buf>. Usually this operation will attempt to read a line of data +from the BIO of maximum length B<len-1>. There are exceptions to this, +however; for example, BIO_gets() on a digest BIO will calculate and +return the digest and other BIOs may not support BIO_gets() at all. +The returned string is always NUL-terminated. + +BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. + +BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>. + +=head1 RETURN VALUES + +All these functions return either the amount of data successfully read or +written (if the return value is positive) or that no data was successfully +read or written if the result is 0 or -1. If the return value is -2 then +the operation is not implemented in the specific BIO type. The trailing +NUL is not included in the length returned by BIO_gets(). + +=head1 NOTES + +A 0 or -1 return is not necessarily an indication of an error. In +particular when the source/sink is non-blocking or of a certain type +it may merely be an indication that no data is currently available and that +the application should retry the operation later. + +One technique sometimes used with blocking sockets is to use a system call +(such as select(), poll() or equivalent) to determine when data is available +and then call read() to read the data. The equivalent with BIOs (that is call +select() on the underlying I/O structure and then call BIO_read() to +read the data) should B<not> be used because a single call to BIO_read() +can cause several reads (and writes in the case of SSL BIOs) on the underlying +I/O structure and may block as a result. Instead select() (or equivalent) +should be combined with non blocking I/O so successive reads will request +a retry instead of blocking. + +See L<BIO_should_retry(3)> for details of how to +determine the cause of a retry and other I/O issues. + +If the BIO_gets() function is not supported by a BIO then it possible to +work around this by adding a buffering BIO L<BIO_f_buffer(3)> +to the chain. + +=head1 SEE ALSO + +L<BIO_should_retry(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_accept.pod b/openssl-1.1.0h/doc/crypto/BIO_s_accept.pod new file mode 100644 index 0000000..ce9995d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_accept.pod @@ -0,0 +1,222 @@ +=pod + +=head1 NAME + +BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, +BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios, +BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD *BIO_s_accept(void); + + long BIO_set_accept_name(BIO *b, char *name); + char *BIO_get_accept_name(BIO *b); + + long BIO_set_accept_port(BIO *b, char *port); + char *BIO_get_accept_port(BIO *b); + + BIO *BIO_new_accept(char *host_port); + + long BIO_set_nbio_accept(BIO *b, int n); + long BIO_set_accept_bios(BIO *b, char *bio); + + long BIO_set_bind_mode(BIO *b, long mode); + long BIO_get_bind_mode(BIO *b); + + int BIO_do_accept(BIO *b); + +=head1 DESCRIPTION + +BIO_s_accept() returns the accept BIO method. This is a wrapper +round the platform's TCP/IP socket accept routines. + +Using accept BIOs, TCP/IP connections can be accepted and data +transferred using only BIO routines. In this way any platform +specific operations are hidden by the BIO abstraction. + +Read and write operations on an accept BIO will perform I/O +on the underlying connection. If no connection is established +and the port (see below) is set up properly then the BIO +waits for an incoming connection. + +Accept BIOs support BIO_puts() but not BIO_gets(). + +If the close flag is set on an accept BIO then any active +connection on that chain is shutdown and the socket closed when +the BIO is freed. + +Calling BIO_reset() on an accept BIO will close any active +connection and reset the BIO into a state where it awaits another +incoming connection. + +BIO_get_fd() and BIO_set_fd() can be called to retrieve or set +the accept socket. See L<BIO_s_fd(3)> + +BIO_set_accept_name() uses the string B<name> to set the accept +name. The name is represented as a string of the form "host:port", +where "host" is the interface to use and "port" is the port. +The host can be "*" or empty which is interpreted as meaning +any interface. If the host is an IPv6 address, it has to be +enclosed in brackets, for example "[::1]:https". "port" has the +same syntax as the port specified in BIO_set_conn_port() for +connect BIOs, that is it can be a numerical port string or a +string to lookup using getservbyname() and a string table. + +BIO_set_accept_port() uses the string B<port> to set the accept +port. "port" has the same syntax as the port specified in +BIO_set_conn_port() for connect BIOs, that is it can be a numerical +port string or a string to lookup using getservbyname() and a string +table. + +BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into +a single call: that is it creates a new accept BIO with port +B<host_port>. + +BIO_set_nbio_accept() sets the accept socket to blocking mode +(the default) if B<n> is 0 or non blocking mode if B<n> is 1. + +BIO_set_accept_bios() can be used to set a chain of BIOs which +will be duplicated and prepended to the chain when an incoming +connection is received. This is useful if, for example, a +buffering or SSL BIO is required for each connection. The +chain of BIOs must not be freed after this call, they will +be automatically freed when the accept BIO is freed. + +BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve +the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set +then another socket cannot be bound to the same port. If +B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the +same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and +attempt is first made to use BIO_BIN_NORMAL, if this fails +and the port is not in use then a second attempt is made +using B<BIO_BIND_REUSEADDR>. + +BIO_do_accept() serves two functions. When it is first +called, after the accept BIO has been setup, it will attempt +to create the accept socket and bind an address to it. Second +and subsequent calls to BIO_do_accept() will await an incoming +connection, or request a retry in non blocking mode. + +=head1 NOTES + +When an accept BIO is at the end of a chain it will await an +incoming connection before processing I/O calls. When an accept +BIO is not at then end of a chain it passes I/O calls to the next +BIO in the chain. + +When a connection is established a new socket BIO is created for +the connection and appended to the chain. That is the chain is now +accept->socket. This effectively means that attempting I/O on +an initial accept socket will await an incoming connection then +perform I/O on it. + +If any additional BIOs have been set using BIO_set_accept_bios() +then they are placed between the socket and the accept BIO, +that is the chain will be accept->otherbios->socket. + +If a server wishes to process multiple connections (as is normally +the case) then the accept BIO must be made available for further +incoming connections. This can be done by waiting for a connection and +then calling: + + connection = BIO_pop(accept); + +After this call B<connection> will contain a BIO for the recently +established connection and B<accept> will now be a single BIO +again which can be used to await further incoming connections. +If no further connections will be accepted the B<accept> can +be freed using BIO_free(). + +If only a single connection will be processed it is possible to +perform I/O using the accept BIO itself. This is often undesirable +however because the accept BIO will still accept additional incoming +connections. This can be resolved by using BIO_pop() (see above) +and freeing up the accept BIO after the initial connection. + +If the underlying accept socket is non-blocking and BIO_do_accept() is +called to await an incoming connection it is possible for +BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens +then it is an indication that an accept attempt would block: the application +should take appropriate action to wait until the underlying socket has +accepted a connection and retry the call. + +BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(), +BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), +BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros. + +=head1 RETURN VALUES + +BIO_do_accept(), +BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(), +BIO_set_accept_bios(), and BIO_set_bind_mode(), return 1 for success and 0 or +-1 for failure. + +BIO_get_accept_name() returns the accept name or NULL on error. + +BIO_get_accept_port() returns the port as a string or NULL on error. + +BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure. + +BIO_new_accept() returns a BIO or NULL on error. + +=head1 EXAMPLE + +This example accepts two connections on port 4444, sends messages +down each and finally closes both down. + + BIO *abio, *cbio, *cbio2; + + /* First call to BIO_accept() sets up accept BIO */ + abio = BIO_new_accept("4444"); + if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error setting up accept\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + + /* Wait for incoming connection */ + if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + fprintf(stderr, "Connection 1 established\n"); + + /* Retrieve BIO for connection */ + cbio = BIO_pop(abio); + BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); + fprintf(stderr, "Sent out data on connection 1\n"); + + /* Wait for another connection */ + if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + fprintf(stderr, "Connection 2 established\n"); + + /* Close accept BIO to refuse further connections */ + cbio2 = BIO_pop(abio); + BIO_free(abio); + BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); + fprintf(stderr, "Sent out data on connection 2\n"); + + BIO_puts(cbio, "Connection 1: Second connection established\n"); + + /* Close the two established connections */ + BIO_free(cbio); + BIO_free(cbio2); + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_bio.pod b/openssl-1.1.0h/doc/crypto/BIO_s_bio.pod new file mode 100644 index 0000000..cb46546 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_bio.pod @@ -0,0 +1,201 @@ +=pod + +=head1 NAME + +BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, +BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, +BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, +BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD *BIO_s_bio(void); + + int BIO_make_bio_pair(BIO *b1, BIO *b2); + int BIO_destroy_bio_pair(BIO *b); + int BIO_shutdown_wr(BIO *b); + + + int BIO_set_write_buf_size(BIO *b, long size); + size_t BIO_get_write_buf_size(BIO *b, long size); + + int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); + + int BIO_get_write_guarantee(BIO *b); + size_t BIO_ctrl_get_write_guarantee(BIO *b); + int BIO_get_read_request(BIO *b); + size_t BIO_ctrl_get_read_request(BIO *b); + int BIO_ctrl_reset_read_request(BIO *b); + +=head1 DESCRIPTION + +BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink +BIOs where data written to either half of the pair is buffered and can be read from +the other half. Both halves must usually by handled by the same application thread +since no locking is done on the internal data structures. + +Since BIO chains typically end in a source/sink BIO it is possible to make this +one half of a BIO pair and have all the data processed by the chain under application +control. + +One typical use of BIO pairs is to place TLS/SSL I/O under application control, this +can be used when the application wishes to use a non standard transport for +TLS/SSL or the normal socket routines are inappropriate. + +Calls to BIO_read() will read data from the buffer or request a retry if no +data is available. + +Calls to BIO_write() will place data in the buffer or request a retry if the +buffer is full. + +The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to +determine the amount of pending data in the read or write buffer. + +BIO_reset() clears any data in the write buffer. + +BIO_make_bio_pair() joins two separate BIOs into a connected pair. + +BIO_destroy_pair() destroys the association between two connected BIOs. Freeing +up any half of the pair will automatically destroy the association. + +BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further +writes on BIO B<b> are allowed (they will return an error). Reads on the other +half of the pair will return any pending data or EOF when all pending data has +been read. + +BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. +If the size is not initialized a default value is used. This is currently +17K, sufficient for a maximum size TLS record. + +BIO_get_write_buf_size() returns the size of the write buffer. + +BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and +BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2> +with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is +zero then the default size is used. BIO_new_bio_pair() does not check whether +B<bio1> or B<bio2> do point to some other BIO, the values are overwritten, +BIO_free() is not called. + +BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum +length of data that can be currently written to the BIO. Writes larger than this +value will return a value from BIO_write() less than the amount requested or if the +buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function +whereas BIO_get_write_guarantee() is a macro. + +BIO_get_read_request() and BIO_ctrl_get_read_request() return the +amount of data requested, or the buffer size if it is less, if the +last read attempt at the other half of the BIO pair failed due to an +empty buffer. This can be used to determine how much data should be +written to the BIO so the next read will succeed: this is most useful +in TLS/SSL applications where the amount of data read is usually +meaningful rather than just a buffer size. After a successful read +this call will return zero. It also will return zero once new data +has been written satisfying the read request or part of it. +Note that BIO_get_read_request() never returns an amount larger +than that returned by BIO_get_write_guarantee(). + +BIO_ctrl_reset_read_request() can also be used to reset the value returned by +BIO_get_read_request() to zero. + +=head1 NOTES + +Both halves of a BIO pair should be freed. That is even if one half is implicit +freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. + +When used in bidirectional applications (such as TLS/SSL) care should be taken to +flush any data in the write buffer. This can be done by calling BIO_pending() +on the other half of the pair and, if any data is pending, reading it and sending +it to the underlying transport. This must be done before any normal processing +(such as calling select() ) due to a request and BIO_should_read() being true. + +To see why this is important consider a case where a request is sent using +BIO_write() and a response read with BIO_read(), this can occur during an +TLS/SSL handshake for example. BIO_write() will succeed and place data in the write +buffer. BIO_read() will initially fail and BIO_should_read() will be true. If +the application then waits for data to be available on the underlying transport +before flushing the write buffer it will never succeed because the request was +never sent! + +BIO_eof() is true if no data is in the peer BIO and the peer BIO has been +shutdown. + +BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), +BIO_set_write_buf_size(), BIO_get_write_buf_size(), +BIO_get_write_guarantee(), and BIO_get_read_request() are implemented +as macros. + +=head1 RETURN VALUES + +BIO_new_bio_pair() returns 1 on success, with the new BIOs available in +B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the +locations for B<bio1> and B<bio2>. Check the error stack for more information. + +[XXXXX: More return values need to be added here] + +=head1 EXAMPLE + +The BIO pair can be used to have full control over the network access of an +application. The application can call select() on the socket as required +without having to go through the SSL-interface. + + BIO *internal_bio, *network_bio; + ... + BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); + SSL_set_bio(ssl, internal_bio, internal_bio); + SSL_operations(); //e.g SSL_read and SSL_write + ... + + application | TLS-engine + | | + +----------> SSL_operations() + | /\ || + | || \/ + | BIO-pair (internal_bio) + | BIO-pair (network_bio) + | || /\ + | \/ || + +-----------< BIO_operations() + | | + | | + socket + + ... + SSL_free(ssl); /* implicitly frees internal_bio */ + BIO_free(network_bio); + ... + +As the BIO pair will only buffer the data and never directly access the +connection, it behaves non-blocking and will return as soon as the write +buffer is full or the read buffer is drained. Then the application has to +flush the write buffer and/or fill the read buffer. + +Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO +and must be transferred to the network. Use BIO_ctrl_get_read_request() to +find out, how many bytes must be written into the buffer before the +SSL_operation() can successfully be continued. + +=head1 WARNING + +As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ +condition, but there is still data in the write buffer. An application must +not rely on the error value of SSL_operation() but must assure that the +write buffer is always flushed first. Otherwise a deadlock may occur as +the peer might be waiting for the data before being able to continue. + +=head1 SEE ALSO + +L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>, +L<BIO_should_retry(3)>, L<BIO_read(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_connect.pod b/openssl-1.1.0h/doc/crypto/BIO_s_connect.pod new file mode 100644 index 0000000..2143acd --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_connect.pod @@ -0,0 +1,200 @@ +=pod + +=head1 NAME + +BIO_set_conn_address, BIO_get_conn_address, +BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, +BIO_get_conn_hostname, +BIO_get_conn_port, +BIO_set_nbio, BIO_do_connect - connect BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD * BIO_s_connect(void); + + BIO *BIO_new_connect(char *name); + + long BIO_set_conn_hostname(BIO *b, char *name); + long BIO_set_conn_port(BIO *b, char *port); + long BIO_set_conn_address(BIO *b, BIO_ADDR *addr); + const char *BIO_get_conn_hostname(BIO *b); + const char *BIO_get_conn_port(BIO *b); + const BIO_ADDR *BIO_get_conn_address(BIO *b); + + long BIO_set_nbio(BIO *b, long n); + + int BIO_do_connect(BIO *b); + +=head1 DESCRIPTION + +BIO_s_connect() returns the connect BIO method. This is a wrapper +round the platform's TCP/IP socket connection routines. + +Using connect BIOs, TCP/IP connections can be made and data +transferred using only BIO routines. In this way any platform +specific operations are hidden by the BIO abstraction. + +Read and write operations on a connect BIO will perform I/O +on the underlying connection. If no connection is established +and the port and hostname (see below) is set up properly then +a connection is established first. + +Connect BIOs support BIO_puts() but not BIO_gets(). + +If the close flag is set on a connect BIO then any active +connection is shutdown and the socket closed when the BIO +is freed. + +Calling BIO_reset() on a connect BIO will close any active +connection and reset the BIO into a state where it can connect +to the same host again. + +BIO_get_fd() places the underlying socket in B<c> if it is not NULL, +it also returns the socket . If B<c> is not NULL it should be of +type (int *). + +BIO_set_conn_hostname() uses the string B<name> to set the hostname. +The hostname can be an IP address; if the address is an IPv6 one, it +must be enclosed with brackets. The hostname can also include the +port in the form hostname:port. + +BIO_set_conn_port() sets the port to B<port>. B<port> can be the +numerical form or a string such as "http". A string will be looked +up first using getservbyname() on the host platform but if that +fails a standard table of port names will be used. This internal +list is http, telnet, socks, https, ssl, ftp, and gopher. + +BIO_set_conn_address() sets the address and port information using +a BIO_ADDR(3ssl). + +BIO_get_conn_hostname() returns the hostname of the connect BIO or +NULL if the BIO is initialized but no hostname is set. +This return value is an internal pointer which should not be modified. + +BIO_get_conn_port() returns the port as a string. +This return value is an internal pointer which should not be modified. + +BIO_get_conn_address() returns the address information as a BIO_ADDR. +This return value is an internal pointer which should not be modified. + +BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is +zero then blocking I/O is set. If B<n> is 1 then non blocking I/O +is set. Blocking I/O is the default. The call to BIO_set_nbio() +should be made before the connection is established because +non blocking I/O is set during the connect process. + +BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into +a single call: that is it creates a new connect BIO with B<name>. + +BIO_do_connect() attempts to connect the supplied BIO. It returns 1 +if the connection was established successfully. A zero or negative +value is returned if the connection could not be established, the +call BIO_should_retry() should be used for non blocking connect BIOs +to determine if the call should be retried. + +=head1 NOTES + +If blocking I/O is set then a non positive return value from any +I/O call is caused by an error condition, although a zero return +will normally mean that the connection was closed. + +If the port name is supplied as part of the host name then this will +override any value set with BIO_set_conn_port(). This may be undesirable +if the application does not wish to allow connection to arbitrary +ports. This can be avoided by checking for the presence of the ':' +character in the passed hostname and either indicating an error or +truncating the string at that point. + +The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), +BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a +connection attempt is made. Before any connection attempt the values +returned are those set by the application itself. + +Applications do not have to call BIO_do_connect() but may wish to do +so to separate the connection process from other I/O processing. + +If non blocking I/O is set then retries will be requested as appropriate. + +It addition to BIO_should_read() and BIO_should_write() it is also +possible for BIO_should_io_special() to be true during the initial +connection process with the reason BIO_RR_CONNECT. If this is returned +then this is an indication that a connection attempt would block, +the application should then take appropriate action to wait until +the underlying socket has connected and retry the call. + +BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(), +BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(), +BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and +BIO_do_connect() are macros. + +=head1 RETURN VALUES + +BIO_s_connect() returns the connect BIO method. + +BIO_get_fd() returns the socket or -1 if the BIO has not +been initialized. + +BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and +BIO_set_conn_int_port() always return 1. + +BIO_get_conn_hostname() returns the connected hostname or NULL is +none was set. + +BIO_get_conn_port() returns a string representing the connected +port or NULL if not set. + +BIO_get_conn_ip() returns a pointer to the connected IP address in +binary form or all zeros if not set. + +BIO_get_conn_int_port() returns the connected port or 0 if none was +set. + +BIO_set_nbio() always returns 1. + +BIO_do_connect() returns 1 if the connection was successfully +established and 0 or -1 if the connection failed. + +=head1 EXAMPLE + +This is example connects to a webserver on the local host and attempts +to retrieve a page and copy the result to standard output. + + + BIO *cbio, *out; + int len; + char tmpbuf[1024]; + + cbio = BIO_new_connect("localhost:http"); + out = BIO_new_fp(stdout, BIO_NOCLOSE); + if (BIO_do_connect(cbio) <= 0) { + fprintf(stderr, "Error connecting to server\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + BIO_puts(cbio, "GET / HTTP/1.0\n\n"); + for ( ; ; ) { + len = BIO_read(cbio, tmpbuf, 1024); + if (len <= 0) + break; + BIO_write(out, tmpbuf, len); + } + BIO_free(cbio); + BIO_free(out); + + +=head1 SEE ALSO + +L<BIO_ADDR(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_fd.pod b/openssl-1.1.0h/doc/crypto/BIO_s_fd.pod new file mode 100644 index 0000000..79c4a59 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_fd.pod @@ -0,0 +1,98 @@ +=pod + +=head1 NAME + +BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD *BIO_s_fd(void); + + int BIO_set_fd(BIO *b, int fd, int c); + int BIO_get_fd(BIO *b, int *c); + + BIO *BIO_new_fd(int fd, int close_flag); + +=head1 DESCRIPTION + +BIO_s_fd() returns the file descriptor BIO method. This is a wrapper +round the platforms file descriptor routines such as read() and write(). + +BIO_read() and BIO_write() read or write the underlying descriptor. +BIO_puts() is supported but BIO_gets() is not. + +If the close flag is set then close() is called on the underlying +file descriptor when the BIO is freed. + +BIO_reset() attempts to change the file pointer to the start of file +such as by using B<lseek(fd, 0, 0)>. + +BIO_seek() sets the file pointer to position B<ofs> from start of file +such as by using B<lseek(fd, ofs, 0)>. + +BIO_tell() returns the current file position such as by calling +B<lseek(fd, 0, 1)>. + +BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close +flag to B<c>. + +BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also +returns the file descriptor. + +BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>. + +=head1 NOTES + +The behaviour of BIO_read() and BIO_write() depends on the behavior of the +platforms read() and write() calls on the descriptor. If the underlying +file descriptor is in a non blocking mode then the BIO will behave in the +manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)> +manual pages. + +File descriptor BIOs should not be used for socket I/O. Use socket BIOs +instead. + +BIO_set_fd() and BIO_get_fd() are implemented as macros. + +=head1 RETURN VALUES + +BIO_s_fd() returns the file descriptor BIO method. + +BIO_set_fd() always returns 1. + +BIO_get_fd() returns the file descriptor or -1 if the BIO has not +been initialized. + +BIO_new_fd() returns the newly allocated BIO or NULL is an error +occurred. + +=head1 EXAMPLE + +This is a file descriptor BIO version of "Hello World": + + BIO *out; + + out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); + BIO_printf(out, "Hello World\n"); + BIO_free(out); + +=head1 SEE ALSO + +L<BIO_seek(3)>, L<BIO_tell(3)>, +L<BIO_reset(3)>, L<BIO_read(3)>, +L<BIO_write(3)>, L<BIO_puts(3)>, +L<BIO_gets(3)>, L<BIO_printf(3)>, +L<BIO_set_close(3)>, L<BIO_get_close(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_file.pod b/openssl-1.1.0h/doc/crypto/BIO_s_file.pod new file mode 100644 index 0000000..e19d824 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_file.pod @@ -0,0 +1,159 @@ +=pod + +=head1 NAME + +BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp, +BIO_read_filename, BIO_write_filename, BIO_append_filename, +BIO_rw_filename - FILE bio + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD * BIO_s_file(void); + BIO *BIO_new_file(const char *filename, const char *mode); + BIO *BIO_new_fp(FILE *stream, int flags); + + BIO_set_fp(BIO *b, FILE *fp, int flags); + BIO_get_fp(BIO *b, FILE **fpp); + + int BIO_read_filename(BIO *b, char *name) + int BIO_write_filename(BIO *b, char *name) + int BIO_append_filename(BIO *b, char *name) + int BIO_rw_filename(BIO *b, char *name) + +=head1 DESCRIPTION + +BIO_s_file() returns the BIO file method. As its name implies it +is a wrapper round the stdio FILE structure and it is a +source/sink BIO. + +Calls to BIO_read() and BIO_write() read and write data to the +underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs. + +BIO_flush() on a file BIO calls the fflush() function on the wrapped +stream. + +BIO_reset() attempts to change the file pointer to the start of file +using fseek(stream, 0, 0). + +BIO_seek() sets the file pointer to position B<ofs> from start of file +using fseek(stream, ofs, 0). + +BIO_eof() calls feof(). + +Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO +is freed. + +BIO_new_file() creates a new file BIO with mode B<mode> the meaning +of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE +flag is set on the returned BIO. + +BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be: +BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying +stream to text mode, default is binary: this only has any effect under +Win32). + +BIO_set_fp() set the fp of a file BIO to B<fp>. B<flags> has the same +meaning as in BIO_new_fp(), it is a macro. + +BIO_get_fp() retrieves the fp of a file BIO, it is a macro. + +BIO_seek() is a macro that sets the position pointer to B<offset> bytes +from the start of file. + +BIO_tell() returns the value of the position pointer. + +BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and +BIO_rw_filename() set the file BIO B<b> to use file B<name> for +reading, writing, append or read write respectively. + +=head1 NOTES + +When wrapping stdout, stdin or stderr the underlying stream should not +normally be closed so the BIO_NOCLOSE flag should be set. + +Because the file BIO calls the underlying stdio functions any quirks +in stdio behaviour will be mirrored by the corresponding BIO. + +On Windows BIO_new_files reserves for the filename argument to be +UTF-8 encoded. In other words if you have to make it work in multi- +lingual environment, encode file names in UTF-8. + +=head1 EXAMPLES + +File BIO "hello world": + + BIO *bio_out; + bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); + BIO_printf(bio_out, "Hello World\n"); + +Alternative technique: + + BIO *bio_out; + bio_out = BIO_new(BIO_s_file()); + if (bio_out == NULL) /* Error ... */ + if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ + BIO_printf(bio_out, "Hello World\n"); + +Write to a file: + + BIO *out; + out = BIO_new_file("filename.txt", "w"); + if (!out) /* Error occurred */ + BIO_printf(out, "Hello World\n"); + BIO_free(out); + +Alternative technique: + + BIO *out; + out = BIO_new(BIO_s_file()); + if (out == NULL) /* Error ... */ + if (!BIO_write_filename(out, "filename.txt")) /* Error ... */ + BIO_printf(out, "Hello World\n"); + BIO_free(out); + +=head1 RETURN VALUES + +BIO_s_file() returns the file BIO method. + +BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error +occurred. + +BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure +(although the current implementation never return 0). + +BIO_seek() returns the same value as the underlying fseek() function: +0 for success or -1 for failure. + +BIO_tell() returns the current file position. + +BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and +BIO_rw_filename() return 1 for success or 0 for failure. + +=head1 BUGS + +BIO_reset() and BIO_seek() are implemented using fseek() on the underlying +stream. The return value for fseek() is 0 for success or -1 if an error +occurred this differs from other types of BIO which will typically return +1 for success and a non positive value if an error occurred. + +=head1 SEE ALSO + +L<BIO_seek(3)>, L<BIO_tell(3)>, +L<BIO_reset(3)>, L<BIO_flush(3)>, +L<BIO_read(3)>, +L<BIO_write(3)>, L<BIO_puts(3)>, +L<BIO_gets(3)>, L<BIO_printf(3)>, +L<BIO_set_close(3)>, L<BIO_get_close(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_mem.pod b/openssl-1.1.0h/doc/crypto/BIO_s_mem.pod new file mode 100644 index 0000000..eb67cbe --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_mem.pod @@ -0,0 +1,124 @@ +=pod + +=head1 NAME + +BIO_s_secmem, +BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, +BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD * BIO_s_mem(void); + const BIO_METHOD * BIO_s_secmem(void); + + BIO_set_mem_eof_return(BIO *b, int v) + long BIO_get_mem_data(BIO *b, char **pp) + BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c) + BIO_get_mem_ptr(BIO *b, BUF_MEM **pp) + + BIO *BIO_new_mem_buf(const void *buf, int len); + +=head1 DESCRIPTION + +BIO_s_mem() return the memory BIO method function. + +A memory BIO is a source/sink BIO which uses memory for its I/O. Data +written to a memory BIO is stored in a BUF_MEM structure which is extended +as appropriate to accommodate the stored data. + +BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used +for buffer storage. + +Any data written to a memory BIO can be recalled by reading from it. +Unless the memory BIO is read only any data read from it is deleted from +the BIO. + +Memory BIOs support BIO_gets() and BIO_puts(). + +If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying +BUF_MEM structure is also freed. + +Calling BIO_reset() on a read write memory BIO clears any data in it if the +flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag +BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and +the data can be read again. + +BIO_eof() is true if no data is in the BIO. + +BIO_ctrl_pending() returns the number of bytes currently stored. + +BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is +empty. If the B<v> is zero then an empty memory BIO will return EOF (that is +it will return zero and BIO_should_retry(b) will be false. If B<v> is non +zero then it will return B<v> when it is empty and it will set the read retry +flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal +positive return value B<v> should be set to a negative value, typically -1. + +BIO_get_mem_data() sets *B<pp> to a pointer to the start of the memory BIOs data +and returns the total amount of data available. It is implemented as a macro. + +BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the +close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE. +It is a macro. + +BIO_get_mem_ptr() places the underlying BUF_MEM structure in *B<pp>. It is +a macro. + +BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>, +if B<len> is -1 then the B<buf> is assumed to be nul terminated and its +length is determined by B<strlen>. The BIO is set to a read only state and +as a result cannot be written to. This is useful when some data needs to be +made available from a static area of memory in the form of a BIO. The +supplied data is read directly from the supplied buffer: it is B<not> copied +first, so the supplied area of memory must be unchanged until the BIO is freed. + +=head1 NOTES + +Writes to memory BIOs will always succeed if memory is available: that is +their size can grow indefinitely. + +Every read from a read write memory BIO will remove the data just read with +an internal copy operation, if a BIO contains a lot of data and it is +read in small chunks the operation can be very slow. The use of a read only +memory BIO avoids this problem. If the BIO must be read write then adding +a buffering BIO to the chain will speed up the process. + +Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will +give undefined results, including perhaps a program crash. + +=head1 BUGS + +There should be an option to set the maximum size of a memory BIO. + +=head1 EXAMPLE + +Create a memory BIO and write some data to it: + + BIO *mem = BIO_new(BIO_s_mem()); + BIO_puts(mem, "Hello World\n"); + +Create a read only memory BIO: + + char data[] = "Hello World"; + BIO *mem; + mem = BIO_new_mem_buf(data, -1); + +Extract the BUF_MEM structure from a memory BIO and then free up the BIO: + + BUF_MEM *bptr; + BIO_get_mem_ptr(mem, &bptr); + BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ + BIO_free(mem); + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_null.pod b/openssl-1.1.0h/doc/crypto/BIO_s_null.pod new file mode 100644 index 0000000..5a1d84d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_null.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +BIO_s_null - null data sink + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD * BIO_s_null(void); + +=head1 DESCRIPTION + +BIO_s_null() returns the null sink BIO method. Data written to +the null sink is discarded, reads return EOF. + +=head1 NOTES + +A null sink BIO behaves in a similar manner to the Unix /dev/null +device. + +A null bio can be placed on the end of a chain to discard any data +passed through it. + +A null sink is useful if, for example, an application wishes to digest some +data by writing through a digest bio but not send the digested data anywhere. +Since a BIO chain must normally include a source/sink BIO this can be achieved +by adding a null sink BIO to the end of the chain + +=head1 RETURN VALUES + +BIO_s_null() returns the null sink BIO method. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_s_socket.pod b/openssl-1.1.0h/doc/crypto/BIO_s_socket.pod new file mode 100644 index 0000000..ad0574a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_s_socket.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +BIO_s_socket, BIO_new_socket - socket BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + const BIO_METHOD *BIO_s_socket(void); + + BIO *BIO_new_socket(int sock, int close_flag); + +=head1 DESCRIPTION + +BIO_s_socket() returns the socket BIO method. This is a wrapper +round the platform's socket routines. + +BIO_read() and BIO_write() read or write the underlying socket. +BIO_puts() is supported but BIO_gets() is not. + +If the close flag is set then the socket is shut down and closed +when the BIO is freed. + +BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>. + +=head1 NOTES + +Socket BIOs also support any relevant functionality of file descriptor +BIOs. + +The reason for having separate file descriptor and socket BIOs is that on some +platforms sockets are not file descriptors and use distinct I/O routines, +Windows is one such platform. Any code mixing the two will not work on +all platforms. + +=head1 RETURN VALUES + +BIO_s_socket() returns the socket BIO method. + +BIO_new_socket() returns the newly allocated BIO or NULL is an error +occurred. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_set_callback.pod b/openssl-1.1.0h/doc/crypto/BIO_set_callback.pod new file mode 100644 index 0000000..27aa4f4 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_set_callback.pod @@ -0,0 +1,221 @@ +=pod + +=head1 NAME + +BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, +BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, +BIO_callback_fn_ex, BIO_callback_fn +- BIO callback functions + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp, + size_t len, int argi, + long argl, int ret, size_t *processed); + typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi, + long argl, long ret); + + void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback); + BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b); + + void BIO_set_callback(BIO *b, BIO_callback_fn cb); + BIO_callback_fn BIO_get_callback(BIO *b); + void BIO_set_callback_arg(BIO *b, char *arg); + char *BIO_get_callback_arg(const BIO *b); + + long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi, + long argl, long ret); + +=head1 DESCRIPTION + +BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO +callback. The callback is called during most high level BIO operations. It can +be used for debugging purposes to trace operations on a BIO or to modify its +operation. + +BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO +callback. New code should not use these functions, but they are retained for +backwards compatibility. Any callback set via BIO_set_callback_ex() will get +called in preference to any set by BIO_set_callback(). + +BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be +used to set and retrieve an argument for use in the callback. + +BIO_debug_callback() is a standard debugging callback which prints +out information relating to each BIO operation. If the callback +argument is set it is interpreted as a BIO to send the information +to, otherwise stderr is used. + +BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn() +is the type of the old format callback function. The meaning of each argument +is described below: + +=over 4 + +=item B<b> + +The BIO the callback is attached to is passed in B<b>. + +=item B<oper> + +B<oper> is set to the operation being performed. For some operations +the callback is called twice, once before and once after the actual +operation, the latter case has B<oper> or'ed with BIO_CB_RETURN. + +=item B<len> + +The length of the data requested to be read or written. This is only useful if +B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS. + +=item B<argp> B<argi> B<argl> + +The meaning of the arguments B<argp>, B<argi> and B<argl> depends on +the value of B<oper>, that is the operation being performed. + +=item B<processed> + +B<processed> is a pointer to a location which will be updated with the amount of +data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE, +BIO_CB_GETS and BIO_CB_PUTS. + +=item B<ret> + +B<ret> is the return value that would be returned to the +application if no callback were present. The actual value returned +is the return value of the callback itself. In the case of callbacks +called before the actual BIO operation 1 is placed in B<ret>, if +the return value is not positive it will be immediately returned to +the application and the BIO operation will not be performed. + +=back + +The callback should normally simply return B<ret> when it has +finished processing, unless it specifically wishes to modify the +value returned to the application. + +=head1 CALLBACK OPERATIONS + +In the notes below, B<callback> defers to the actual callback +function that is called. + +=over 4 + +=item B<BIO_free(b)> + + callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL) + +or + + callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) + +is called before the free operation. + +=item B<BIO_read_ex(b, data, dlen, readbytes)> + + callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, readbytes) + +or + + callback(b, BIO_CB_READ, data, dlen, 0L, 1L) + +is called before the read and + + callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, readbytes) + +or + + callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue) + +after. + +=item B<BIO_write(b, data, dlen, written)> + + callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, written) + +or + + callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L) + +is called before the write and + + callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, written) + +or + + callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue) + +after. + +=item B<BIO_gets(b, buf, size)> + + callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL) + +or + + callback(b, BIO_CB_GETS, buf, size, 0L, 1L) + +is called before the operation and + + callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue, readbytes) + +or + + callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue) + +after. + +=item B<BIO_puts(b, buf)> + + callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL); + +or + + callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L) + +is called before the operation and + + callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, written) + +or + + callback(b, BIO_CB_WRITE|BIO_CB_RETURN, buf, 0, 0L, retvalue) + +after. + +=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> + + callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL) + +or + + callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L) + +is called before the call and + + callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL) + +or + + callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) + +after. + +=back + +=head1 EXAMPLE + +The BIO_debug_callback() function is a good example, its source is +in crypto/bio/bio_cb.c + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BIO_should_retry.pod b/openssl-1.1.0h/doc/crypto/BIO_should_retry.pod new file mode 100644 index 0000000..d01d5bb --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BIO_should_retry.pod @@ -0,0 +1,132 @@ +=pod + +=head1 NAME + +BIO_should_read, BIO_should_write, +BIO_should_io_special, BIO_retry_type, BIO_should_retry, +BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry +functions + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_should_read(BIO *b); + int BIO_should_write(BIO *b); + int BIO_should_io_special(iBIO *b); + int BIO_retry_type(BIO *b); + int BIO_should_retry(BIO *b); + + BIO *BIO_get_retry_BIO(BIO *bio, int *reason); + int BIO_get_retry_reason(BIO *bio); + void BIO_set_retry_reason(BIO *bio, int reason); + +=head1 DESCRIPTION + +These functions determine why a BIO is not able to read or write data. +They will typically be called after a failed BIO_read() or BIO_write() +call. + +BIO_should_retry() is true if the call that produced this condition +should then be retried at a later time. + +If BIO_should_retry() is false then the cause is an error condition. + +BIO_should_read() is true if the cause of the condition is that a BIO +needs to read data. + +BIO_should_write() is true if the cause of the condition is that a BIO +needs to read data. + +BIO_should_io_special() is true if some "special" condition, that is a +reason other than reading or writing is the cause of the condition. + +BIO_retry_type() returns a mask of the cause of a retry condition +consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, +B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of +these. + +BIO_get_retry_BIO() determines the precise reason for the special +condition, it returns the BIO that caused this condition and if +B<reason> is not NULL it contains the reason code. The meaning of +the reason code and the action that should be taken depends on +the type of BIO that resulted in this condition. + +BIO_get_retry_reason() returns the reason for a special condition if +passed the relevant BIO, for example as returned by BIO_get_retry_BIO(). + +BIO_set_retry_reason() sets the retry reason for a special condition for a given +BIO. This would usually only be called by BIO implementations. + +=head1 NOTES + +BIO_should_read(), BIO_should_write(), BIO_should_io_special(), +BIO_retry_type(), and BIO_should_retry(), are implemented as macros. + +If BIO_should_retry() returns false then the precise "error condition" +depends on the BIO type that caused it and the return code of the BIO +operation. For example if a call to BIO_read() on a socket BIO returns +0 and BIO_should_retry() is false then the cause will be that the +connection closed. A similar condition on a file BIO will mean that it +has reached EOF. Some BIO types may place additional information on +the error queue. For more details see the individual BIO type manual +pages. + +If the underlying I/O structure is in a blocking mode almost all current +BIO types will not request a retry, because the underlying I/O +calls will not. If the application knows that the BIO type will never +signal a retry then it need not call BIO_should_retry() after a failed +BIO I/O call. This is typically done with file BIOs. + +SSL BIOs are the only current exception to this rule: they can request a +retry even if the underlying I/O structure is blocking, if a handshake +occurs during a call to BIO_read(). An application can retry the failed +call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY +on the underlying SSL structure. + +While an application may retry a failed non blocking call immediately +this is likely to be very inefficient because the call will fail +repeatedly until data can be processed or is available. An application +will normally wait until the necessary condition is satisfied. How +this is done depends on the underlying I/O structure. + +For example if the cause is ultimately a socket and BIO_should_read() +is true then a call to select() may be made to wait until data is +available and then retry the BIO operation. By combining the retry +conditions of several non blocking BIOs in a single select() call +it is possible to service several BIOs in a single thread, though +the performance may be poor if SSL BIOs are present because long delays +can occur during the initial handshake process. + +It is possible for a BIO to block indefinitely if the underlying I/O +structure cannot process or return any data. This depends on the behaviour of +the platforms I/O functions. This is often not desirable: one solution +is to use non blocking I/O and use a timeout on the select() (or +equivalent) call. + +=head1 BUGS + +The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: +that is they cannot retry after a partial read or write. This is usually +worked around by only passing the relevant data to ASN1 functions when +the entire structure can be read or written. + +=head1 SEE ALSO + +L<bio> + +=head1 HISTORY + +The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_BLINDING_new.pod b/openssl-1.1.0h/doc/crypto/BN_BLINDING_new.pod new file mode 100644 index 0000000..4229e75 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_BLINDING_new.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, +BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, +BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread, +BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags, +BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, + BIGNUM *mod); + void BN_BLINDING_free(BN_BLINDING *b); + int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx); + int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); + int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); + int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, + BN_CTX *ctx); + int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b, + BN_CTX *ctx); + int BN_BLINDING_is_current_thread(BN_BLINDING *b); + void BN_BLINDING_set_current_thread(BN_BLINDING *b); + int BN_BLINDING_lock(BN_BLINDING *b); + int BN_BLINDING_unlock(BN_BLINDING *b); + unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); + void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); + BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, + const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, + int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), + BN_MONT_CTX *m_ctx); + +=head1 DESCRIPTION + +BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies +the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object. + +BN_BLINDING_free() frees the B<BN_BLINDING> structure. +If B<b> is NULL, nothing is done. + +BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring +the B<A> and B<Ai> or, after specific number of uses and if the +necessary parameters are set, by re-creating the blinding parameters. + +BN_BLINDING_convert_ex() multiplies 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 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. + +BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper +functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() +with B<r> set to NULL. + +BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING> +structure is owned by the current thread. This is to help users +provide proper locking if needed for multi-threaded use. + +BN_BLINDING_set_current_thread() sets the current thread as the +owner of the B<BN_BLINDING> structure. + +BN_BLINDING_lock() locks the B<BN_BLINDING> structure. + +BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure. + +BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently +there are two supported flags: B<BN_BLINDING_NO_UPDATE> and +B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the +automatic update of the B<BN_BLINDING> parameters after each use +and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation +of the B<BN_BLINDING> parameters after a fixed number of uses (currently +32). In newly allocated B<BN_BLINDING> objects no flags are set. +BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags. + +BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters +using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and +B<m_ctx> can be used to pass special functions for exponentiation +(normally BN_mod_exp_mont() and B<BN_MONT_CTX>). + +=head1 RETURN VALUES + +BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure +or NULL in case of an error. + +BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(), +BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on +success and 0 if an error occurred. + +BN_BLINDING_is_current_thread() returns 1 if the current thread owns +the B<BN_BLINDING> object, 0 otherwise. + +BN_BLINDING_set_current_thread() doesn't return anything. + +BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation +succeeded or 0 on error. + +BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags +(a B<unsigned long> value). + +BN_BLINDING_create_param() returns the newly created B<BN_BLINDING> +parameters or NULL on error. + +=head1 HISTORY + +BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it +deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id(). + +=head1 COPYRIGHT + +Copyright 2005-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_CTX_new.pod b/openssl-1.1.0h/doc/crypto/BN_CTX_new.pod new file mode 100644 index 0000000..623fcd5 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_CTX_new.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BN_CTX *BN_CTX_new(void); + + BN_CTX *BN_CTX_secure_new(void); + + void BN_CTX_free(BN_CTX *c); + +=head1 DESCRIPTION + +A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by +library functions. Since dynamic memory allocation to create B<BIGNUM>s +is rather expensive when used in conjunction with repeated subroutine +calls, the B<BN_CTX> structure is used. + +BN_CTX_new() allocates and initializes a B<BN_CTX> structure. +BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure +but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the +B<BIGNUM>s. + +BN_CTX_free() frees the components of the B<BN_CTX>, and if it was +created by BN_CTX_new(), also the structure itself. +If L<BN_CTX_start(3)> has been used on the B<BN_CTX>, +L<BN_CTX_end(3)> must be called before the B<BN_CTX> +may be freed by BN_CTX_free(). +If B<c> is NULL, nothing is done. + +=head1 RETURN VALUES + +BN_CTX_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>. +If the allocation fails, +they return B<NULL> and sets an error code that can be obtained by +L<ERR_get_error(3)>. + +BN_CTX_free() has no return values. + +=head1 REMOVED FUNCTIONALITY + + void BN_CTX_init(BN_CTX *c); + +BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should +replace use of BN_CTX_init with BN_CTX_new instead: + + BN_CTX *ctx; + ctx = BN_CTX_new(); + if(!ctx) /* Handle error */ + ... + BN_CTX_free(ctx); + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<BN_add(3)>, +L<BN_CTX_start(3)> + +=head1 HISTORY + +BN_CTX_init() was removed in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_CTX_start.pod b/openssl-1.1.0h/doc/crypto/BN_CTX_start.pod new file mode 100644 index 0000000..372da50 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_CTX_start.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + void BN_CTX_start(BN_CTX *ctx); + + BIGNUM *BN_CTX_get(BN_CTX *ctx); + + void BN_CTX_end(BN_CTX *ctx); + +=head1 DESCRIPTION + +These functions are used to obtain temporary B<BIGNUM> variables from +a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)>) +in order to save the overhead of repeatedly creating and +freeing B<BIGNUM>s in functions that are called from inside a loop. + +A function must call BN_CTX_start() first. Then, BN_CTX_get() may be +called repeatedly to obtain temporary B<BIGNUM>s. All BN_CTX_get() +calls must be made before calling any other functions that use the +B<ctx> as an argument. + +Finally, BN_CTX_end() must be called before returning from the function. +When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from +BN_CTX_get() become invalid. + +=head1 RETURN VALUES + +BN_CTX_start() and BN_CTX_end() return no values. + +BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error. +Once BN_CTX_get() has failed, the subsequent calls will return B<NULL> +as well, so it is sufficient to check the return value of the last +BN_CTX_get() call. In case of an error, an error code is set, which +can be obtained by L<ERR_get_error(3)>. + + +=head1 SEE ALSO + +L<BN_CTX_new(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_add.pod b/openssl-1.1.0h/doc/crypto/BN_add.pod new file mode 100644 index 0000000..db3b0d4 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_add.pod @@ -0,0 +1,127 @@ +=pod + +=head1 NAME + +BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add, +BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_exp, BN_mod_exp, BN_gcd - +arithmetic operations on BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); + + int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); + + int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + + int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); + + int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, + BN_CTX *ctx); + + int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); + + int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); + + int BN_mod_add(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + BN_CTX *ctx); + + int BN_mod_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + BN_CTX *ctx); + + int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + BN_CTX *ctx); + + int BN_mod_sqr(BIGNUM *r, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); + + int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); + + int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx); + + int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + +=head1 DESCRIPTION + +BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>). +I<r> may be the same B<BIGNUM> as I<a> or I<b>. + +BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>). +I<r> may be the same B<BIGNUM> as I<a> or I<b>. + +BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>). +I<r> may be the same B<BIGNUM> as I<a> or I<b>. +For multiplication by powers of 2, use L<BN_lshift(3)>. + +BN_sqr() takes the square of I<a> and places the result in I<r> +(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>. +This function is faster than BN_mul(r,a,a). + +BN_div() divides I<a> by I<d> and places the result in I<dv> and the +remainder in I<rem> (C<dv=a/d, rem=a%d>). Either of I<dv> and I<rem> may +be B<NULL>, in which case the respective value is not returned. +The result is rounded towards zero; thus if I<a> is negative, the +remainder will be zero or negative. +For division by powers of 2, use BN_rshift(3). + +BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>. + +BN_nnmod() reduces I<a> modulo I<m> and places the non-negative +remainder in I<r>. + +BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative +result in I<r>. + +BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the +non-negative result in I<r>. + +BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative +remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be +the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for +repeated computations using the same modulus, see +L<BN_mod_mul_montgomery(3)> and +L<BN_mod_mul_reciprocal(3)>. + +BN_mod_sqr() takes the square of I<a> modulo B<m> and places the +result in I<r>. + +BN_exp() raises I<a> to the I<p>-th power and places the result in I<r> +(C<r=a^p>). This function is faster than repeated applications of +BN_mul(). + +BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p % +m>). This function uses less time and space than BN_exp(). + +BN_gcd() computes the greatest common divisor of I<a> and I<b> and +places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or +I<b>. + +For all functions, I<ctx> is a previously allocated B<BN_CTX> used for +temporary variables; see L<BN_CTX_new(3)>. + +Unless noted otherwise, the result B<BIGNUM> must be different from +the arguments. + +=head1 RETURN VALUES + +For all functions, 1 is returned for success, 0 on error. The return +value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>). +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<BN_CTX_new(3)>, +L<BN_add_word(3)>, L<BN_set_bit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_add_word.pod b/openssl-1.1.0h/doc/crypto/BN_add_word.pod new file mode 100644 index 0000000..6c69bc4 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_add_word.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic +functions on BIGNUMs with integers + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_add_word(BIGNUM *a, BN_ULONG w); + + int BN_sub_word(BIGNUM *a, BN_ULONG w); + + int BN_mul_word(BIGNUM *a, BN_ULONG w); + + BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); + + BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); + +=head1 DESCRIPTION + +These functions perform arithmetic operations on BIGNUMs with unsigned +integers. They are much more efficient than the normal BIGNUM +arithmetic operations. + +BN_add_word() adds B<w> to B<a> (C<a+=w>). + +BN_sub_word() subtracts B<w> from B<a> (C<a-=w>). + +BN_mul_word() multiplies B<a> and B<w> (C<a*=w>). + +BN_div_word() divides B<a> by B<w> (C<a/=w>) and returns the remainder. + +BN_mod_word() returns the remainder of B<a> divided by B<w> (C<a%w>). + +For BN_div_word() and BN_mod_word(), B<w> must not be 0. + +=head1 RETURN VALUES + +BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0 +on error. The error codes can be obtained by L<ERR_get_error(3)>. + +BN_mod_word() and BN_div_word() return B<a>%B<w> on success and +B<(BN_ULONG)-1> if an error occurred. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<BN_add(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_bn2bin.pod b/openssl-1.1.0h/doc/crypto/BN_bn2bin.pod new file mode 100644 index 0000000..ac46948 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_bn2bin.pod @@ -0,0 +1,116 @@ +=pod + +=head1 NAME + +BN_bn2binpad, +BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec, +BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi, +BN_mpi2bn - format conversions + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_bn2bin(const BIGNUM *a, unsigned char *to); + int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen); + BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); + + int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen); + BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret); + + char *BN_bn2hex(const BIGNUM *a); + char *BN_bn2dec(const BIGNUM *a); + int BN_hex2bn(BIGNUM **a, const char *str); + int BN_dec2bn(BIGNUM **a, const char *str); + + int BN_print(BIO *fp, const BIGNUM *a); + int BN_print_fp(FILE *fp, const BIGNUM *a); + + int BN_bn2mpi(const BIGNUM *a, unsigned char *to); + BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); + +=head1 DESCRIPTION + +BN_bn2bin() converts the absolute value of B<a> into big-endian form +and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of +memory. + +BN_bn2binpad() also converts the absolute value of B<a> into big-endian form +and stores it at B<to>. B<tolen> indicates the length of the output buffer +B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than +BN_num_bytes(B<a>) an error is returned. + +BN_bin2bn() converts the positive integer in big-endian form of length +B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is +NULL, a new B<BIGNUM> is created. + +BN_bn2lebinpad() and BN_bin2lbn() are identical to BN_bn2binpad() and +BN_bin2bn() except the buffer is in little-endian format. + +BN_bn2hex() and BN_bn2dec() return printable strings containing the +hexadecimal and decimal encoding of B<a> respectively. For negative +numbers, the string is prefaced with a leading '-'. The string must be +freed later using OPENSSL_free(). + +BN_hex2bn() takes as many characters as possible from the string B<str>, +including the leading character '-' which means negative, to form a valid +hexadecimal number representation and converts them to a B<BIGNUM> and +stores it in **B<bn>. If *B<bn> is NULL, a new B<BIGNUM> is created. If +B<bn> is NULL, it only computes the length of valid representation. +A "negative zero" is converted to zero. +BN_dec2bn() is the same using the decimal system. + +BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>, +with a leading '-' for negative numbers, to the B<BIO> or B<FILE> +B<fp>. + +BN_bn2mpi() and BN_mpi2bn() convert B<BIGNUM>s from and to a format +that consists of the number's length in bytes represented as a 4-byte +big-endian number, and the number itself in big-endian format, where +the most significant bit signals a negative number (the representation +of numbers with the MSB set is prefixed with null byte). + +BN_bn2mpi() stores the representation of B<a> at B<to>, where B<to> +must be large enough to hold the result. The size can be determined by +calling BN_bn2mpi(B<a>, NULL). + +BN_mpi2bn() converts the B<len> bytes long representation at B<s> to +a B<BIGNUM> and stores it at B<ret>, or in a newly allocated B<BIGNUM> +if B<ret> is NULL. + +=head1 RETURN VALUES + +BN_bn2bin() returns the length of the big-endian number placed at B<to>. +BN_bin2bn() returns the B<BIGNUM>, NULL on error. + +BN_bn2binpad() returns the number of bytes written or -1 if the supplied +buffer is too small. + +BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL +on error. BN_hex2bn() and BN_dec2bn() return the number of characters +used in parsing, or 0 on error, in which +case no new B<BIGNUM> will be created. + +BN_print_fp() and BN_print() return 1 on success, 0 on write errors. + +BN_bn2mpi() returns the length of the representation. BN_mpi2bn() +returns the B<BIGNUM>, and NULL on error. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<BN_zero(3)>, +L<ASN1_INTEGER_to_BN(3)>, +L<BN_num_bytes(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_cmp.pod b/openssl-1.1.0h/doc/crypto/BN_cmp.pod new file mode 100644 index 0000000..95d162f --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_cmp.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_cmp(BIGNUM *a, BIGNUM *b); + int BN_ucmp(BIGNUM *a, BIGNUM *b); + + int BN_is_zero(BIGNUM *a); + int BN_is_one(BIGNUM *a); + int BN_is_word(BIGNUM *a, BN_ULONG w); + int BN_is_odd(BIGNUM *a); + +=head1 DESCRIPTION + +BN_cmp() compares the numbers B<a> and B<b>. BN_ucmp() compares their +absolute values. + +BN_is_zero(), BN_is_one() and BN_is_word() test if B<a> equals 0, 1, +or B<w> respectively. BN_is_odd() tests if a is odd. + +BN_is_zero(), BN_is_one(), BN_is_word() and BN_is_odd() are macros. + +=head1 RETURN VALUES + +BN_cmp() returns -1 if B<a> E<lt> B<b>, 0 if B<a> == B<b> and 1 if +B<a> E<gt> B<b>. BN_ucmp() is the same using the absolute values +of B<a> and B<b>. + +BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if +the condition is true, 0 otherwise. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_copy.pod b/openssl-1.1.0h/doc/crypto/BN_copy.pod new file mode 100644 index 0000000..46de544 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_copy.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +BN_copy, BN_dup, BN_with_flags - copy BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from); + + BIGNUM *BN_dup(const BIGNUM *from); + + void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags); + +=head1 DESCRIPTION + +BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM> +containing the value B<from>. + +BN_with_flags creates a B<temporary> shallow copy of B<b> in B<dest>. It places +significant restrictions on the copied data. Applications that do no adhere to +these restrictions may encounter unexpected side effects or crashes. For that +reason use of this function is discouraged. Any flags provided in B<flags> will +be set in B<dest> in addition to any flags already set in B<b>. For example this +might commonly be used to create a temporary copy of a BIGNUM with the +B<BN_FLG_CONSTTIME> flag set for constant time operations. The temporary copy in +B<dest> will share some internal state with B<b>. For this reason the following +restrictions apply to the use of B<dest>: + +=over 2 + +=item * + +B<dest> should be a newly allocated BIGNUM obtained via a call to BN_new(). It +should not have been used for other purposes or initialised in any way. + +=item * + +B<dest> must only be used in "read-only" operations, i.e. typically those +functions where the relevant parameter is declared "const". + +=item * + +B<dest> must be used and freed before any further subsequent use of B<b> + +=back + +=head1 RETURN VALUES + +BN_copy() returns B<to> on success, NULL on error. BN_dup() returns +the new B<BIGNUM>, and NULL on error. The error codes can be obtained +by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_generate_prime.pod b/openssl-1.1.0h/doc/crypto/BN_generate_prime.pod new file mode 100644 index 0000000..c97536b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_generate_prime.pod @@ -0,0 +1,194 @@ +=pod + +=head1 NAME + +BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, +BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, +BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test +for primality + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add, + const BIGNUM *rem, BN_GENCB *cb); + + int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb); + + int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, + int do_trial_division, BN_GENCB *cb); + + int BN_GENCB_call(BN_GENCB *cb, int a, int b); + + BN_GENCB *BN_GENCB_new(void); + + void BN_GENCB_free(BN_GENCB *cb); + + void BN_GENCB_set_old(BN_GENCB *gencb, + void (*callback)(int, int, void *), void *cb_arg); + + void BN_GENCB_set(BN_GENCB *gencb, + int (*callback)(int, int, BN_GENCB *), void *cb_arg); + + void *BN_GENCB_get_arg(BN_GENCB *cb); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x00908000L + BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, + BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); + + int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int, + void *), BN_CTX *ctx, void *cb_arg); + + int BN_is_prime_fasttest(const BIGNUM *a, int checks, + void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg, + int do_trial_division); + #endif + +=head1 DESCRIPTION + +BN_generate_prime_ex() generates a pseudo-random prime number of +at least bit length B<bits>. +If B<ret> is not B<NULL>, it will be used to store the number. + +If B<cb> is not B<NULL>, it is used as follows: + +=over 2 + +=item * + +B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th +potential prime number. + +=item * + +While the number is being tested for primality, +B<BN_GENCB_call(cb, 1, j)> is called as described below. + +=item * + +When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called. + +=back + +The prime may have to fulfill additional requirements for use in +Diffie-Hellman key exchange: + +If B<add> is not B<NULL>, the prime will fulfill the condition p % B<add> +== B<rem> (p % B<add> == 1 if B<rem> == B<NULL>) in order to suit a given +generator. + +If B<safe> is true, it will be a safe prime (i.e. a prime p so +that (p-1)/2 is also prime). + +The PRNG must be seeded prior to calling BN_generate_prime_ex(). +The prime number generation has a negligible error probability. + +BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is +prime. The following tests are performed until one of them shows that +B<p> is composite; if B<p> passes all these tests, it is considered +prime. + +BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>, +first attempts trial division by a number of small primes; +if no divisors are found by this test and B<cb> is not B<NULL>, +B<BN_GENCB_call(cb, 1, -1)> is called. +If B<do_trial_division == 0>, this test is skipped. + +Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin +probabilistic primality test with B<nchecks> iterations. If +B<nchecks == BN_prime_checks>, a number of iterations is used that +yields a false positive rate of at most 2^-80 for random input. + +If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called +after the j-th iteration (j = 0, 1, ...). B<ctx> is a +pre-allocated B<BN_CTX> (to save the overhead of allocating and +freeing the structure in a loop), or B<NULL>. + +BN_GENCB_call calls the callback function held in the B<BN_GENCB> structure +and passes the ints B<a> and B<b> as arguments. There are two types of +B<BN_GENCB> structure that are supported: "new" style and "old" style. New +programs should prefer the "new" style, whilst the "old" style is provided +for backwards compatibility purposes. + +A BN_GENCB structure should be created through a call to BN_GENCB_new(), +and freed through a call to BN_GENCB_free(). + +For "new" style callbacks a BN_GENCB structure should be initialised with a +call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of +type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>. +"Old" style callbacks are the same except they are initialised with a call +to BN_GENCB_set_old() and B<callback> is of type +B<void (*callback)(int, int, void *)>. + +A callback is invoked through a call to B<BN_GENCB_call>. This will check +the type of the callback and will invoke B<callback(a, b, gencb)> for new +style callbacks or B<callback(a, b, cb_arg)> for old style. + +It is possible to obtained the argument associated with a BN_GENCB structure +(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. + +BN_generate_prime (deprecated) works in the same way as +BN_generate_prime_ex but expects an old style callback function +directly in the B<callback> parameter, and an argument to pass to it in +the B<cb_arg>. Similarly BN_is_prime and BN_is_prime_fasttest are +deprecated and can be compared to BN_is_prime_ex and +BN_is_prime_fasttest_ex respectively. + +=head1 RETURN VALUES + +BN_generate_prime_ex() return 1 on success or 0 on error. + +BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and +BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is +prime with an error probability of less than 0.25^B<nchecks>, and +-1 on error. + +BN_generate_prime() returns the prime number on success, B<NULL> otherwise. + +BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL> +otherwise. + +BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB +structure. + +Callback functions should return 1 on success or 0 on error. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 REMOVED FUNCTIONALITY + +As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure +directly, as in: + + BN_GENCB callback; + +Instead applications should create a BN_GENCB structure using BN_GENCB_new: + + BN_GENCB *callback; + callback = BN_GENCB_new(); + if(!callback) /* handle error */ + ... + BN_GENCB_free(callback); + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<RAND_bytes(3)> + +=head1 HISTORY + +BN_GENCB_new(), BN_GENCB_free(), +and BN_GENCB_get_arg() were added in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_mod_inverse.pod b/openssl-1.1.0h/doc/crypto/BN_mod_inverse.pod new file mode 100644 index 0000000..cb84a14 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_mod_inverse.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +BN_mod_inverse - compute inverse modulo n + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, + BN_CTX *ctx); + +=head1 DESCRIPTION + +BN_mod_inverse() computes the inverse of B<a> modulo B<n> +places the result in B<r> (C<(a*r)%n==1>). If B<r> is NULL, +a new B<BIGNUM> is created. + +B<ctx> is a previously allocated B<BN_CTX> used for temporary +variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>. + +=head1 RETURN VALUES + +BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and +NULL on error. The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<BN_add(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_mod_mul_montgomery.pod b/openssl-1.1.0h/doc/crypto/BN_mod_mul_montgomery.pod new file mode 100644 index 0000000..81056c7 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_mod_mul_montgomery.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +BN_mod_mul_montgomery, BN_MONT_CTX_new, +BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy, +BN_from_montgomery, BN_to_montgomery - Montgomery multiplication + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BN_MONT_CTX *BN_MONT_CTX_new(void); + void BN_MONT_CTX_free(BN_MONT_CTX *mont); + + int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); + BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); + + int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, + BN_MONT_CTX *mont, BN_CTX *ctx); + + int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, + BN_CTX *ctx); + + int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, + BN_CTX *ctx); + +=head1 DESCRIPTION + +These functions implement Montgomery multiplication. They are used +automatically when L<BN_mod_exp(3)> is called with suitable input, +but they may be useful when several operations are to be performed +using the same modulus. + +BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure. + +BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m> +by precomputing its inverse and a value R. + +BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>. + +BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if +it was created by BN_MONT_CTX_new(), also the structure itself. +If B<mont> is NULL, nothing is done. + +BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places +the result in I<r>. + +BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1. + +BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R. +Note that I<a> must be non-negative and smaller than the modulus. + +For all functions, I<ctx> is a previously allocated B<BN_CTX> used for +temporary variables. + +=head1 RETURN VALUES + +BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL +on error. + +BN_MONT_CTX_free() has no return value. + +For the other functions, 1 is returned for success, 0 on error. +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 WARNING + +The inputs must be reduced modulo B<m>, otherwise the result will be +outside the expected range. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<BN_add(3)>, +L<BN_CTX_new(3)> + +=head1 HISTORY + +BN_MONT_CTX_init() was removed in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_mod_mul_reciprocal.pod b/openssl-1.1.0h/doc/crypto/BN_mod_mul_reciprocal.pod new file mode 100644 index 0000000..d480fed --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_mod_mul_reciprocal.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, +BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using +reciprocal + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BN_RECP_CTX *BN_RECP_CTX_new(void); + void BN_RECP_CTX_free(BN_RECP_CTX *recp); + + int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); + + int BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *a, BN_RECP_CTX *recp, + BN_CTX *ctx); + + int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, + BN_RECP_CTX *recp, BN_CTX *ctx); + +=head1 DESCRIPTION + +BN_mod_mul_reciprocal() can be used to perform an efficient +L<BN_mod_mul(3)> operation when the operation will be performed +repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m> +using B<recp>=1/B<m>, which is set as described below. B<ctx> is a +previously allocated B<BN_CTX> used for temporary variables. + +BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure. + +BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it +was created by BN_RECP_CTX_new(), also the structure itself. +If B<recp> is NULL, nothing is done. + +BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing +1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an +integer. The result and the number of bits it was shifted left will +later be stored in B<recp>. + +BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient +in B<dv> and the remainder in B<rem>. + +The B<BN_RECP_CTX> structure cannot be shared between threads. + +=head1 RETURN VALUES + +BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL +on error. + +BN_RECP_CTX_free() has no return value. + +For the other functions, 1 is returned for success, 0 on error. +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<BN_add(3)>, +L<BN_CTX_new(3)> + +=head1 HISTORY + +BN_RECP_CTX_init() was removed in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_new.pod b/openssl-1.1.0h/doc/crypto/BN_new.pod new file mode 100644 index 0000000..08aae5e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_new.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + BIGNUM *BN_new(void); + + BIGNUM *BN_secure_new(void); + + void BN_clear(BIGNUM *a); + + void BN_free(BIGNUM *a); + + void BN_clear_free(BIGNUM *a); + +=head1 DESCRIPTION + +BN_new() allocates and initializes a B<BIGNUM> structure. +BN_secure_new() does the same except that the secure heap +OPENSSL_secure_malloc(3) is used to store the value. + +BN_clear() is used to destroy sensitive data such as keys when they +are no longer needed. It erases the memory used by B<a> and sets it +to the value 0. + +BN_free() frees the components of the B<BIGNUM>, and if it was created +by BN_new(), also the structure itself. BN_clear_free() additionally +overwrites the data before the memory is returned to the system. +If B<a> is NULL, nothing is done. + +=head1 RETURN VALUES + +BN_new() and BN_secure_new() +return a pointer to the B<BIGNUM> initialised to the value 0. +If the allocation fails, +they return B<NULL> and set an error code that can be obtained +by L<ERR_get_error(3)>. + +BN_clear(), BN_free() and BN_clear_free() have no return values. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 HISTORY + +BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_num_bytes.pod b/openssl-1.1.0h/doc/crypto/BN_num_bytes.pod new file mode 100644 index 0000000..9e0465d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_num_bytes.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_num_bytes(const BIGNUM *a); + + int BN_num_bits(const BIGNUM *a); + + int BN_num_bits_word(BN_ULONG w); + +=head1 DESCRIPTION + +BN_num_bytes() returns the size of a B<BIGNUM> in bytes. + +BN_num_bits_word() returns the number of significant bits in a word. +If we take 0x00000432 as an example, it returns 11, not 16, not 32. +Basically, except for a zero, it returns I<floor(log2(w))+1>. + +BN_num_bits() returns the number of significant bits in a B<BIGNUM>, +following the same principle as BN_num_bits_word(). + +BN_num_bytes() is a macro. + +=head1 RETURN VALUES + +The size. + +=head1 NOTES + +Some have tried using BN_num_bits() on individual numbers in RSA keys, +DH keys and DSA keys, and found that they don't always come up with +the number of bits they expected (something like 512, 1024, 2048, +...). This is because generating a number with some specific number +of bits doesn't always set the highest bits, thereby making the number +of I<significant> bits a little lower. If you want to know the "key +size" of such a key, either use functions like RSA_size(), DH_size() +and DSA_size(), or use BN_num_bytes() and multiply with 8 (although +there's no real guarantee that will match the "key size", just a lot +more probability). + +=head1 SEE ALSO + +L<DH_size(3)>, L<DSA_size(3)>, +L<RSA_size(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_rand.pod b/openssl-1.1.0h/doc/crypto/BN_rand.pod new file mode 100644 index 0000000..08d14de --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_rand.pod @@ -0,0 +1,67 @@ +=pod + +=head1 NAME + +BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); + + int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); + + int BN_rand_range(BIGNUM *rnd, BIGNUM *range); + + int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); + +=head1 DESCRIPTION + +BN_rand() generates a cryptographically strong pseudo-random number of +B<bits> in length and stores it in B<rnd>. +If B<bits> is less than zero, or too small to +accommodate the requirements specified by the B<top> and B<bottom> +parameters, an error is returned. +The B<top> parameters specifies +requirements on the most significant bit of the generated number. +If it is B<BN_RAND_TOP_ANY>, there is no constraint. +If it is B<BN_RAND_TOP_ONE>, the top bit must be one. +If it is B<BN_RAND_TOP_TWO>, the two most significant bits of +the number will be set to 1, so that the product of two such random +numbers will always have 2*B<bits> length. +If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it +is B<BN_RAND_BOTTOM_ANY> it can be odd or even. +If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>. + +BN_pseudo_rand() does the same, but pseudo-random numbers generated by +this function are not necessarily unpredictable. They can be used for +non-cryptographic purposes and for certain purposes in cryptographic +protocols, but usually not for key generation etc. + +BN_rand_range() generates a cryptographically strong pseudo-random +number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>. +BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(), +and hence numbers generated by it are not necessarily unpredictable. + +The PRNG must be seeded prior to calling BN_rand() or BN_rand_range(). + +=head1 RETURN VALUES + +The functions return 1 on success, 0 on error. +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<RAND_add(3)>, L<RAND_bytes(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_set_bit.pod b/openssl-1.1.0h/doc/crypto/BN_set_bit.pod new file mode 100644 index 0000000..af02983 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_set_bit.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift, +BN_lshift1, BN_rshift, BN_rshift1 - bit operations on BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + int BN_set_bit(BIGNUM *a, int n); + int BN_clear_bit(BIGNUM *a, int n); + + int BN_is_bit_set(const BIGNUM *a, int n); + + int BN_mask_bits(BIGNUM *a, int n); + + int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); + int BN_lshift1(BIGNUM *r, BIGNUM *a); + + int BN_rshift(BIGNUM *r, BIGNUM *a, int n); + int BN_rshift1(BIGNUM *r, BIGNUM *a); + +=head1 DESCRIPTION + +BN_set_bit() sets bit B<n> in B<a> to 1 (C<a|=(1E<lt>E<lt>n)>). The +number is expanded if necessary. + +BN_clear_bit() sets bit B<n> in B<a> to 0 (C<a&=~(1E<lt>E<lt>n)>). An +error occurs if B<a> is shorter than B<n> bits. + +BN_is_bit_set() tests if bit B<n> in B<a> is set. + +BN_mask_bits() truncates B<a> to an B<n> bit number +(C<a&=~((~0)E<gt>E<gt>n)>). An error occurs if B<a> already is +shorter than B<n> bits. + +BN_lshift() shifts B<a> left by B<n> bits and places the result in +B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts +B<a> left by one and places the result in B<r> (C<r=2*a>). + +BN_rshift() shifts B<a> right by B<n> bits and places the result in +B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts +B<a> right by one and places the result in B<r> (C<r=a/2>). + +For the shift functions, B<r> and B<a> may be the same variable. + +=head1 RETURN VALUES + +BN_is_bit_set() returns 1 if the bit is set, 0 otherwise. + +All other functions return 1 for success, 0 on error. The error codes +can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<BN_num_bytes(3)>, L<BN_add(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_swap.pod b/openssl-1.1.0h/doc/crypto/BN_swap.pod new file mode 100644 index 0000000..9f77f22 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_swap.pod @@ -0,0 +1,26 @@ +=pod + +=head1 NAME + +BN_swap - exchange BIGNUMs + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + void BN_swap(BIGNUM *a, BIGNUM *b); + +=head1 DESCRIPTION + +BN_swap() exchanges the values of I<a> and I<b>. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BN_zero.pod b/openssl-1.1.0h/doc/crypto/BN_zero.pod new file mode 100644 index 0000000..2ca8850 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BN_zero.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment +operations + +=head1 SYNOPSIS + + #include <openssl/bn.h> + + void BN_zero(BIGNUM *a); + int BN_one(BIGNUM *a); + + const BIGNUM *BN_value_one(void); + + int BN_set_word(BIGNUM *a, BN_ULONG w); + BN_ULONG BN_get_word(BIGNUM *a); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x00908000L + int BN_zero(BIGNUM *a); + #endif + +=head1 DESCRIPTION + +B<BN_ULONG> is a macro that will be an unsigned integral type optimied +for the most efficient implementation on the local platform. + +BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and +B<w> respectively. BN_zero() and BN_one() are macros. + +BN_value_one() returns a B<BIGNUM> constant of value 1. This constant +is useful for use in comparisons and assignment. + +BN_get_word() returns B<a>, if it can be represented as a B<BN_ULONG>. + +=head1 RETURN VALUES + +BN_get_word() returns the value B<a>, or all-bits-set if B<a> cannot +be represented as a B<BN_ULONG>. + +BN_one(), BN_set_word() and the deprecated version of BN_zero() +return 1 on success, 0 otherwise. +BN_value_one() returns the constant. +The preferred version of BN_zero() never fails and returns no value. + +=head1 BUGS + +If a B<BIGNUM> is equal to the value of all-bits-set, it will collide +with the error condition returned by BN_get_word() which uses that +as an error value. + +B<BN_ULONG> should probably be a typedef. + +=head1 SEE ALSO + +L<BN_bn2bin(3)> + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/BUF_MEM_new.pod b/openssl-1.1.0h/doc/crypto/BUF_MEM_new.pod new file mode 100644 index 0000000..1d89159 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/BUF_MEM_new.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow, +BUF_MEM_grow_clean, BUF_reverse +- simple character array structure + +standard C library equivalents + +=head1 SYNOPSIS + + #include <openssl/buffer.h> + + BUF_MEM *BUF_MEM_new(void); + + BUF_MEM *BUF_MEM_new_ex(unsigned long flags); + + void BUF_MEM_free(BUF_MEM *a); + + int BUF_MEM_grow(BUF_MEM *str, int len); + size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len); + + void BUF_reverse(unsigned char *out, const unsigned char *in, size_t size); + +=head1 DESCRIPTION + +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. + +BUF_MEM_new() allocates a new buffer of zero size. + +BUF_MEM_new_ex() allocates a buffer with the specified flags. +The flag B<BUF_MEM_FLAG_SECURE> specifies that the B<data> pointer +should be allocated on the secure heap; see L<CRYPTO_secure_malloc(3)>. + +BUF_MEM_free() frees up an already existing buffer. The data is zeroed +before freeing up in case the buffer contains sensitive data. + +BUF_MEM_grow() changes the size of an already existing buffer to +B<len>. Any data already in the buffer is preserved if it increases in +size. + +BUF_MEM_grow_clean() is similar to BUF_MEM_grow() but it sets any free'd +or additionally-allocated memory to zero. + +BUF_reverse() reverses B<size> bytes at B<in> into B<out>. If B<in> +is NULL, the array is reversed in-place. + +=head1 RETURN VALUES + +BUF_MEM_new() returns the buffer or NULL on error. + +BUF_MEM_free() has no return value. + +BUF_MEM_grow() and BUF_MEM_grow_clean() return +zero on error or the new size (i.e., B<len>). + +=head1 SEE ALSO + +L<bio(7)>, +L<CRYPTO_secure_malloc(3)>. + +=head1 HISTORY + +BUF_MEM_new_ex() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_add0_cert.pod b/openssl-1.1.0h/doc/crypto/CMS_add0_cert.pod new file mode 100644 index 0000000..a5be002 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_add0_cert.pod @@ -0,0 +1,71 @@ +=pod + +=head1 NAME + +CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls +- CMS certificate and CRL utility functions + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_add0_cert(CMS_ContentInfo *cms, X509 *cert); + int CMS_add1_cert(CMS_ContentInfo *cms, X509 *cert); + STACK_OF(X509) *CMS_get1_certs(CMS_ContentInfo *cms); + + int CMS_add0_crl(CMS_ContentInfo *cms, X509_CRL *crl); + int CMS_add1_crl(CMS_ContentInfo *cms, X509_CRL *crl); + STACK_OF(X509_CRL) *CMS_get1_crls(CMS_ContentInfo *cms); + + +=head1 DESCRIPTION + +CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>. +must be of type signed data or enveloped data. + +CMS_get1_certs() returns all certificates in B<cms>. + +CMS_add0_crl() and CMS_add1_crl() add CRL B<crl> to B<cms>. CMS_get1_crls() +returns any CRLs in B<cms>. + +=head1 NOTES + +The CMS_ContentInfo structure B<cms> must be of type signed data or enveloped +data or an error will be returned. + +For signed data certificates and CRLs are added to the B<certificates> and +B<crls> fields of SignedData structure. For enveloped data they are added to +B<OriginatorInfo>. + +As the B<0> implies CMS_add0_cert() adds B<cert> internally to B<cms> and it +must not be freed up after the call as opposed to CMS_add1_cert() where B<cert> +must be freed up. + +The same certificate or CRL must not be added to the same cms structure more +than once. + +=head1 RETURN VALUES + +CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return +1 for success and 0 for failure. + +CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs +or NULL if there are none or an error occurs. The only error which will occur +in practice is if the B<cms> type is invalid. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<CMS_sign(3)>, +L<CMS_encrypt(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_add1_recipient_cert.pod b/openssl-1.1.0h/doc/crypto/CMS_add1_recipient_cert.pod new file mode 100644 index 0000000..0dae5cf --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_add1_recipient_cert.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *recip, unsigned int flags); + + CMS_RecipientInfo *CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid, unsigned char *key, size_t keylen, unsigned char *id, size_t idlen, ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId, ASN1_TYPE *otherType); + +=head1 DESCRIPTION + +CMS_add1_recipient_cert() adds recipient B<recip> to CMS_ContentInfo enveloped +data structure B<cms> as a KeyTransRecipientInfo structure. + +CMS_add0_recipient_key() adds symmetric key B<key> of length B<keylen> using +wrapping algorithm B<nid>, identifier B<id> of length B<idlen> and optional +values B<date>, B<otherTypeId> and B<otherType> to CMS_ContentInfo enveloped +data structure B<cms> as a KEKRecipientInfo structure. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_encrypt() with the flag B<CMS_PARTIAL> set. + +=head1 NOTES + +The main purpose of this function is to provide finer control over a CMS +enveloped data structure where the simpler CMS_encrypt() function defaults are +not appropriate. For example if one or more KEKRecipientInfo structures +need to be added. New attributes can also be added using the returned +CMS_RecipientInfo structure and the CMS attribute utility functions. + +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If B<CMS_USE_KEYID> is set it will use the subject key +identifier value instead. An error occurs if all recipient certificates do not +have a subject key identifier extension. + +Currently only AES based key wrapping algorithms are supported for B<nid>, +specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. +If B<nid> is set to B<NID_undef> then an AES wrap algorithm will be used +consistent with B<keylen>. + +=head1 RETURN VALUES + +CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal +pointer to the CMS_RecipientInfo structure just added or NULL if an error +occurs. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_decrypt(3)>, +L<CMS_final(3)>, + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_add1_signer.pod b/openssl-1.1.0h/doc/crypto/CMS_add1_signer.pod new file mode 100644 index 0000000..f4738e0 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_add1_signer.pod @@ -0,0 +1,106 @@ +=pod + +=head1 NAME + +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_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_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>. + +The CMS_ContentInfo structure should be obtained from an initial call to +CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a +valid CMS_ContentInfo SignedData structure. + +If the B<md> parameter is B<NULL> then the default digest for the public +key algorithm will be used. + +Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo +structure is not complete and must be finalized either by streaming (if +applicable) or a call to CMS_final(). + +The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo +structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags +are both set. + +=head1 NOTES + +The main purpose of CMS_add1_signer() is to provide finer control +over a CMS signed data structure where the simpler CMS_sign() function defaults +are not appropriate. For example if multiple signers or non default digest +algorithms are needed. New attributes can also be added using the returned +CMS_SignerInfo structure and the CMS attribute utility functions or the +CMS signed receipt request functions. + +Any of the following flags (ored together) can be passed in the B<flags> +parameter. + +If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content +digest value from the CMS_ContentInfo structure: to add a signer to an existing +structure. An error occurs if a matching digest value cannot be found to copy. +The returned CMS_ContentInfo structure will be valid and finalized when this +flag is set. + +If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the +CMS_SignerInfo structure will not be finalized so additional attributes +can be added. In this case an explicit call to CMS_SignerInfo_sign() is +needed to finalize it. + +If B<CMS_NOCERTS> is set the signer's certificate will not be included in the +CMS_ContentInfo structure, the signer's certificate must still be supplied in +the B<signcert> parameter though. This can reduce the size of the signature if +the signers certificate can be obtained by other means: for example a +previously signed message. + +The SignedData structure includes several CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes +will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are +omitted. + +OpenSSL will by default identify signing certificates using issuer name +and serial number. If B<CMS_USE_KEYID> is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. + +CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo +structure just added, this can be used to set additional attributes +before it is finalized. + +=head1 RETURN VALUES + +CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo +structure just added or NULL if an error occurs. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_final(3)>, + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_compress.pod b/openssl-1.1.0h/doc/crypto/CMS_compress.pod new file mode 100644 index 0000000..e405108 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_compress.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +CMS_compress - create a CMS CompressedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *CMS_compress(BIO *in, int comp_nid, unsigned int flags); + +=head1 DESCRIPTION + +CMS_compress() creates and returns a CMS CompressedData structure. B<comp_nid> +is the compression algorithm to use or B<NID_undef> to use the default +algorithm (zlib compression). B<in> is the content to be compressed. +B<flags> is an optional set of flags. + +=head1 NOTES + +The only currently supported compression algorithm is zlib using the NID +NID_zlib_compression. + +If zlib support is not compiled into OpenSSL then CMS_compress() will return +an error. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are +prepended to the data. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<CMS_BINARY> is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. If B<CMS_BINARY> is set then +B<CMS_TEXT> is ignored. + +If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is +returned suitable for streaming I/O: no data is read from the BIO B<in>. + +The compressed data is included in the CMS_ContentInfo structure, unless +B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in +practice and is not supported by SMIME_write_CMS(). + +=head1 NOTES + +If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is +B<not> complete and outputting its contents via a function that does not +properly finalize the B<CMS_ContentInfo> structure will give unpredictable +results. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B<BIO> directly using +BIO_new_CMS(). + +Additional compression parameters such as the zlib compression level cannot +currently be set. + +=head1 RETURN VALUES + +CMS_compress() returns either a CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_uncompress(3)> + +=head1 HISTORY + +The B<CMS_STREAM> flag was added in OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_decrypt.pod b/openssl-1.1.0h/doc/crypto/CMS_decrypt.pod new file mode 100644 index 0000000..b3b196c --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_decrypt.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +CMS_decrypt - decrypt content from a CMS envelopedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags); + +=head1 DESCRIPTION + +CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData +structure. B<pkey> is the private key of the recipient, B<cert> is the +recipient's certificate, B<out> is a BIO to write the content to and +B<flags> is an optional set of flags. + +The B<dcont> parameter is used in the rare case where the encrypted content +is detached. It will normally be set to NULL. + +=head1 NOTES + +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. 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 +in advance using the CMS utility functions such as CMS_set1_pkey(). In this +case both B<cert> and B<pkey> should be set to NULL. + +To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() +and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and +B<cert> and B<pkey> set to NULL. + +The following flags can be passed in the B<flags> parameter. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted +from the content. If the content is not of type B<text/plain> then an error is +returned. + +=head1 RETURN VALUES + +CMS_decrypt() returns either 1 for success or 0 for failure. +The error can be obtained from ERR_get_error(3) + +=head1 BUGS + +The lack of single pass processing and the need to hold all data in memory as +mentioned in CMS_verify() also applies to CMS_decrypt(). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_encrypt(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_encrypt.pod b/openssl-1.1.0h/doc/crypto/CMS_encrypt.pod new file mode 100644 index 0000000..0ed4262 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_encrypt.pod @@ -0,0 +1,104 @@ +=pod + +=head1 NAME + +CMS_encrypt - create a CMS envelopedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags); + +=head1 DESCRIPTION + +CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs> +is a list of recipient certificates. B<in> is the content to be encrypted. +B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. + +=head1 NOTES + +Only certificates carrying RSA keys are supported so the recipient certificates +supplied to this function must all contain RSA public keys, though they do not +have to be signed using the RSA algorithm. + +EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use +because most clients will support it. + +The algorithm passed in the B<cipher> parameter must support ASN1 encoding of +its parameters. + +Many browsers implement a "sign and encrypt" option which is simply an S/MIME +envelopedData containing an S/MIME signed message. This can be readily produced +by storing the S/MIME signed message in a memory BIO and passing it to +CMS_encrypt(). + +The following flags can be passed in the B<flags> parameter. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are +prepended to the data. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<CMS_BINARY> is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. If B<CMS_BINARY> is set then +B<CMS_TEXT> is ignored. + +OpenSSL will by default identify recipient certificates using issuer name +and serial number. If B<CMS_USE_KEYID> is set it will use the subject key +identifier value instead. An error occurs if all recipient certificates do not +have a subject key identifier extension. + +If the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is +returned suitable for streaming I/O: no data is read from the BIO B<in>. + +If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is +returned to which additional recipients and attributes can be added before +finalization. + +The data being encrypted is included in the CMS_ContentInfo structure, unless +B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in +practice and is not supported by SMIME_write_CMS(). + +=head1 NOTES + +If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is +B<not> complete and outputting its contents via a function that does not +properly finalize the B<CMS_ContentInfo> structure will give unpredictable +results. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B<BIO> directly using +BIO_new_CMS(). + +The recipients specified in B<certs> use a CMS KeyTransRecipientInfo info +structure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL> +and CMS_add0_recipient_key(). + +The parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients +added later using CMS_add1_recipient_cert() or CMS_add0_recipient_key(). + +=head1 RETURN VALUES + +CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_decrypt(3)> + +=head1 HISTORY + +The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_final.pod b/openssl-1.1.0h/doc/crypto/CMS_final.pod new file mode 100644 index 0000000..264fe7b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_final.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +CMS_final - finalise a CMS_ContentInfo structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_final(CMS_ContentInfo *cms, BIO *data, BIO *dcont, unsigned int flags); + +=head1 DESCRIPTION + +CMS_final() finalises the structure B<cms>. It's purpose is to perform any +operations necessary on B<cms> (digest computation for example) and set the +appropriate fields. The parameter B<data> contains the content to be +processed. The B<dcont> parameter contains a BIO to write content to after +processing: this is only used with detached data and will usually be set to +NULL. + +=head1 NOTES + +This function will normally be called when the B<CMS_PARTIAL> flag is used. It +should only be used when streaming is not performed because the streaming +I/O functions perform finalisation operations internally. + +=head1 RETURN VALUES + +CMS_final() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_encrypt(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_get0_RecipientInfos.pod b/openssl-1.1.0h/doc/crypto/CMS_get0_RecipientInfos.pod new file mode 100644 index 0000000..6c33c22 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_get0_RecipientInfos.pod @@ -0,0 +1,130 @@ +=pod + +=head1 NAME + +CMS_get0_RecipientInfos, CMS_RecipientInfo_type, +CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp, +CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, +CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, +CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt +- CMS envelopedData RecipientInfo routines + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + STACK_OF(CMS_RecipientInfo) *CMS_get0_RecipientInfos(CMS_ContentInfo *cms); + int CMS_RecipientInfo_type(CMS_RecipientInfo *ri); + + int CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); + int CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert); + int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey); + + int CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri, X509_ALGOR **palg, ASN1_OCTET_STRING **pid, ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid, ASN1_TYPE **pothertype); + int CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri, const unsigned char *id, size_t idlen); + int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen); + + int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); + int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri); + +=head1 DESCRIPTION + +The function CMS_get0_RecipientInfos() returns all the CMS_RecipientInfo +structures associated with a CMS EnvelopedData structure. + +CMS_RecipientInfo_type() returns the type of CMS_RecipientInfo structure B<ri>. +It will currently return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, +CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. + +CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient +identifier associated with a specific CMS_RecipientInfo structure B<ri>, which +must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in +B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. + +CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the +CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS. +It returns zero if the comparison is successful and non zero if not. + +CMS_RecipientInfo_set0_pkey() associates the private key B<pkey> with +the CMS_RecipientInfo structure B<ri>, which must be of type +CMS_RECIPINFO_TRANS. + +CMS_RecipientInfo_kekri_get0_id() retrieves the key information from the +CMS_RecipientInfo structure B<ri> which must be of type CMS_RECIPINFO_KEK. Any +of the remaining parameters can be NULL if the application is not interested in +the value of a field. Where a field is optional and absent NULL will be written +to the corresponding parameter. The keyEncryptionAlgorithm field is written to +B<palg>, the B<keyIdentifier> field is written to B<pid>, the B<date> field if +present is written to B<pdate>, if the B<other> field is present the components +B<keyAttrId> and B<keyAttr> are written to parameters B<potherid> and +B<pothertype>. + +CMS_RecipientInfo_kekri_id_cmp() compares the ID in the B<id> and B<idlen> +parameters against the B<keyIdentifier> CMS_RecipientInfo structure B<ri>, +which must be of type CMS_RECIPINFO_KEK. It returns zero if the comparison is +successful and non zero if not. + +CMS_RecipientInfo_set0_key() associates the symmetric key B<key> of length +B<keylen> with the CMS_RecipientInfo structure B<ri>, which must be of type +CMS_RECIPINFO_KEK. + +CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure +B<ri> in structure B<cms>. A key must have been associated with the structure +first. + +CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure +B<ri> in structure B<cms>. A key must have been associated with the structure +first and the content encryption key must be available: for example by a +previous call to CMS_RecipientInfo_decrypt(). + +=head1 NOTES + +The main purpose of these functions is to enable an application to lookup +recipient keys using any appropriate technique when the simpler method +of CMS_decrypt() is not appropriate. + +In typical usage and application will retrieve all CMS_RecipientInfo structures +using CMS_get0_RecipientInfos() and check the type of each using +CMS_RecpientInfo_type(). Depending on the type the CMS_RecipientInfo structure +can be ignored or its key identifier data retrieved using an appropriate +function. Then if the corresponding secret or private key can be obtained by +any appropriate means it can then associated with the structure and +CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called +with a NULL key to decrypt the enveloped content. + +The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an +existing enveloped data structure. Typically an application will first decrypt +an appropriate CMS_RecipientInfo structure to make the content encrypt key +available, it will then add a new recipient using a function such as +CMS_add1_recipient_cert() and finally encrypt the content encryption key +using CMS_RecipientInfo_encrypt(). + +=head1 RETURN VALUES + +CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if +an error occurs. + +CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), +CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and +CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. +CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs. + +CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 +for a successful comparison and non zero otherwise. + +Any error can be obtained from L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_decrypt(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_get0_SignerInfos.pod b/openssl-1.1.0h/doc/crypto/CMS_get0_SignerInfos.pod new file mode 100644 index 0000000..e5532c9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_get0_SignerInfos.pod @@ -0,0 +1,89 @@ +=pod + +=head1 NAME + +CMS_SignerInfo_set1_signer_cert, +CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, +CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp +- CMS signedData signer functions + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms); + + int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno); + ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si); + int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert); + void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer); + +=head1 DESCRIPTION + +The function CMS_get0_SignerInfos() returns all the CMS_SignerInfo structures +associated with a CMS signedData structure. + +CMS_SignerInfo_get0_signer_id() retrieves the certificate signer identifier +associated with a specific CMS_SignerInfo structure B<si>. Either the +keyidentifier will be set in B<keyid> or B<both> issuer name and serial number +in B<issuer> and B<sno>. + +CMS_SignerInfo_get0_signature() retrieves the signature associated with +B<si> in a pointer to an ASN1_OCTET_STRING structure. This pointer returned +corresponds to the internal signature value if B<si> so it may be read or +modified. + +CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer +identifier B<si>. It returns zero if the comparison is successful and non zero +if not. + +CMS_SignerInfo_set1_signer_cert() sets the signers certificate of B<si> to +B<signer>. + +=head1 NOTES + +The main purpose of these functions is to enable an application to lookup +signers certificates using any appropriate technique when the simpler method +of CMS_verify() is not appropriate. + +In typical usage and application will retrieve all CMS_SignerInfo structures +using CMS_get0_SignerInfo() and retrieve the identifier information using +CMS. It will then obtain the signer certificate by some unspecified means +(or return and error if it cannot be found) and set it using +CMS_SignerInfo_set1_signer_cert(). + +Once all signer certificates have been set CMS_verify() can be used. + +Although CMS_get0_SignerInfos() can return NULL is an error occur B<or> if +there are no signers this is not a problem in practice because the only +error which can occur is if the B<cms> structure is not of type signedData +due to application error. + +=head1 RETURN VALUES + +CMS_get0_SignerInfos() returns all CMS_SignerInfo structures, or NULL there +are no signers or an error occurs. + +CMS_SignerInfo_get0_signer_id() returns 1 for success and 0 for failure. + +CMS_SignerInfo_cert_cmp() returns 0 for a successful comparison and non +zero otherwise. + +CMS_SignerInfo_set1_signer_cert() does not return a value. + +Any error can be obtained from L<ERR_get_error(3)> + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_verify(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_get0_type.pod b/openssl-1.1.0h/doc/crypto/CMS_get0_type.pod new file mode 100644 index 0000000..cad8d3f --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_get0_type.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + const ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms); + int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid); + const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms); + ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +CMS_get0_type() returns the content type of a CMS_ContentInfo structure as +and ASN1_OBJECT pointer. An application can then decide how to process the +CMS_ContentInfo structure based on this value. + +CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo +structure. It should be called with CMS functions with the B<CMS_PARTIAL> +flag and B<before> the structure is finalised, otherwise the results are +undefined. + +ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded +content type. + +CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer +containing the embedded content. + +=head1 NOTES + +As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and +CMS_get0_content() return internal pointers which should B<not> be freed up. +CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up +after use. + +The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value +using OBJ_obj2nid(). For the currently supported content types the following +values are returned: + + NID_pkcs7_data + NID_pkcs7_signed + NID_pkcs7_digest + NID_id_smime_ct_compressedData: + NID_pkcs7_encrypted + NID_pkcs7_enveloped + +The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING> +content pointer. That means that for example: + + ASN1_OCTET_STRING **pconf = CMS_get0_content(cms); + +B<*pconf> could be NULL if there is no embedded content. Applications can +access, modify or create the embedded content in a B<CMS_ContentInfo> structure +using this function. Applications usually will not need to modify the +embedded content as it is normally set by higher level functions. + +=head1 RETURN VALUES + +CMS_get0_type() and CMS_get0_eContentType() return and ASN1_OBJECT structure. + +CMS_set1_eContentType() returns 1 for success or 0 if an error occurred. The +error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_get1_ReceiptRequest.pod b/openssl-1.1.0h/doc/crypto/CMS_get1_ReceiptRequest.pod new file mode 100644 index 0000000..79f5f42 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_get1_ReceiptRequest.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ReceiptRequest *CMS_ReceiptRequest_create0(unsigned char *id, int idlen, int allorfirst, STACK_OF(GENERAL_NAMES) *receiptList, STACK_OF(GENERAL_NAMES) *receiptsTo); + int CMS_add1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest *rr); + int CMS_get1_ReceiptRequest(CMS_SignerInfo *si, CMS_ReceiptRequest **prr); + void CMS_ReceiptRequest_get0_values(CMS_ReceiptRequest *rr, ASN1_STRING **pcid, int *pallorfirst, STACK_OF(GENERAL_NAMES) **plist, STACK_OF(GENERAL_NAMES) **prto); + +=head1 DESCRIPTION + +CMS_ReceiptRequest_create0() creates a signed receipt request structure. The +B<signedContentIdentifier> field is set using B<id> and B<idlen>, or it is set +to 32 bytes of pseudo random data if B<id> is NULL. If B<receiptList> is NULL +the allOrFirstTier option in B<receiptsFrom> is used and set to the value of +the B<allorfirst> parameter. If B<receiptList> is not NULL the B<receiptList> +option in B<receiptsFrom> is used. The B<receiptsTo> parameter specifies the +B<receiptsTo> field value. + +The CMS_add1_ReceiptRequest() function adds a signed receipt request B<rr> +to SignerInfo structure B<si>. + +int CMS_get1_ReceiptRequest() looks for a signed receipt request in B<si>, if +any is found it is decoded and written to B<prr>. + +CMS_ReceiptRequest_get0_values() retrieves the values of a receipt request. +The signedContentIdentifier is copied to B<pcid>. If the B<allOrFirstTier> +option of B<receiptsFrom> is used its value is copied to B<pallorfirst> +otherwise the B<receiptList> field is copied to B<plist>. The B<receiptsTo> +parameter is copied to B<prto>. + +=head1 NOTES + +For more details of the meaning of the fields see RFC2634. + +The contents of a signed receipt should only be considered meaningful if the +corresponding CMS_ContentInfo structure can be successfully verified using +CMS_verify(). + +=head1 RETURN VALUES + +CMS_ReceiptRequest_create0() returns a signed receipt request structure or +NULL if an error occurred. + +CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred. + +CMS_get1_ReceiptRequest() returns 1 is a signed receipt request is found and +decoded. It returns 0 if a signed receipt request is not present and -1 if +it is present but malformed. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_sign_receipt(3)>, L<CMS_verify(3)> +L<CMS_verify_receipt(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_sign.pod b/openssl-1.1.0h/doc/crypto/CMS_sign.pod new file mode 100644 index 0000000..396deef --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_sign.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +CMS_sign - create a CMS SignedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *CMS_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, unsigned int flags); + +=head1 DESCRIPTION + +CMS_sign() creates and returns a CMS SignedData structure. B<signcert> is +the certificate to sign with, B<pkey> is the corresponding private key. +B<certs> is an optional additional set of certificates to include in the CMS +structure (for example any intermediate CAs in the chain). Any or all of +these parameters can be B<NULL>, see B<NOTES> below. + +The data to be signed is read from BIO B<data>. + +B<flags> is an optional set of flags. + +=head1 NOTES + +Any of the following flags (ored together) can be passed in the B<flags> +parameter. + +Many S/MIME clients expect the signed content to include valid MIME headers. If +the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are prepended +to the data. + +If B<CMS_NOCERTS> is set the signer's certificate will not be included in the +CMS_ContentInfo structure, the signer's certificate must still be supplied in +the B<signcert> parameter though. This can reduce the size of the signature if +the signers certificate can be obtained by other means: for example a +previously signed message. + +The data being signed is included in the CMS_ContentInfo structure, unless +B<CMS_DETACHED> is set in which case it is omitted. This is used for +CMS_ContentInfo detached signatures which are used in S/MIME plaintext signed +messages for example. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<CMS_BINARY> is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. + +The SignedData structure includes several CMS signedAttributes including the +signing time, the CMS content type and the supported list of ciphers in an +SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes +will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are +omitted. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192 +bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. +If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is +not loaded. + +OpenSSL will by default identify signing certificates using issuer name +and serial number. If B<CMS_USE_KEYID> is set it will use the subject key +identifier value instead. An error occurs if the signing certificate does not +have a subject key identifier extension. + +If the flags B<CMS_STREAM> is set then the returned B<CMS_ContentInfo> +structure is just initialized ready to perform the signing operation. The +signing is however B<not> performed and the data to be signed is not read from +the B<data> parameter. Signing is deferred until after the data has been +written. In this way data can be signed in a single pass. + +If the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is +output to which additional signers and capabilities can be added before +finalization. + +If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is +B<not> complete and outputting its contents via a function that does not +properly finalize the B<CMS_ContentInfo> structure will give unpredictable +results. + +Several functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), +PEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B<BIO> directly using +BIO_new_CMS(). + +If a signer is specified it will use the default digest for the signing +algorithm. This is B<SHA1> for both RSA and DSA keys. + +If B<signcert> and B<pkey> are NULL then a certificates only CMS structure is +output. + +The function CMS_sign() is a basic CMS signing function whose output will be +suitable for many purposes. For finer control of the output format the +B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the +B<CMS_PARTIAL> flag set. Then one or more signers can be added using the +function CMS_sign_add1_signer(), non default digests can be used and custom +attributes added. CMS_final() must then be called to finalize the +structure if streaming is not enabled. + +=head1 BUGS + +Some attributes such as counter signatures are not supported. + +=head1 RETURN VALUES + +CMS_sign() returns either a valid CMS_ContentInfo structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_verify(3)> + +=head1 HISTORY + +The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8, +it is supported for embedded data in OpenSSL 1.0.0 and later. + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_sign_receipt.pod b/openssl-1.1.0h/doc/crypto/CMS_sign_receipt.pod new file mode 100644 index 0000000..8ea6df1 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_sign_receipt.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +CMS_sign_receipt - create a CMS signed receipt + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *CMS_sign_receipt(CMS_SignerInfo *si, X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, unsigned int flags); + +=head1 DESCRIPTION + +CMS_sign_receipt() creates and returns a CMS signed receipt structure. B<si> is +the B<CMS_SignerInfo> structure containing the signed receipt request. +B<signcert> is the certificate to sign with, B<pkey> is the corresponding +private key. B<certs> is an optional additional set of certificates to include +in the CMS structure (for example any intermediate CAs in the chain). + +B<flags> is an optional set of flags. + +=head1 NOTES + +This functions behaves in a similar way to CMS_sign() except the flag values +B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_NOATTR>, B<CMS_TEXT> and B<CMS_STREAM> +are not supported since they do not make sense in the context of signed +receipts. + +=head1 RETURN VALUES + +CMS_sign_receipt() returns either a valid CMS_ContentInfo structure or NULL if +an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<CMS_verify_receipt(3)>, +L<CMS_sign(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_uncompress.pod b/openssl-1.1.0h/doc/crypto/CMS_uncompress.pod new file mode 100644 index 0000000..80f9c0d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_uncompress.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +CMS_uncompress - uncompress a CMS CompressedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_uncompress(CMS_ContentInfo *cms, BIO *dcont, BIO *out, unsigned int flags); + +=head1 DESCRIPTION + +CMS_uncompress() extracts and uncompresses the content from a CMS +CompressedData structure B<cms>. B<data> is a BIO to write the content to and +B<flags> is an optional set of flags. + +The B<dcont> parameter is used in the rare case where the compressed content +is detached. It will normally be set to NULL. + +=head1 NOTES + +The only currently supported compression algorithm is zlib: if the structure +indicates the use of any other algorithm an error is returned. + +If zlib support is not compiled into OpenSSL then CMS_uncompress() will always +return an error. + +The following flags can be passed in the B<flags> parameter. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted +from the content. If the content is not of type B<text/plain> then an error is +returned. + +=head1 RETURN VALUES + +CMS_uncompress() returns either 1 for success or 0 for failure. The error can +be obtained from ERR_get_error(3) + +=head1 BUGS + +The lack of single pass processing and the need to hold all data in memory as +mentioned in CMS_verify() also applies to CMS_decompress(). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_compress(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_verify.pod b/openssl-1.1.0h/doc/crypto/CMS_verify.pod new file mode 100644 index 0000000..c2ff57b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_verify.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +CMS_verify, CMS_get0_signers - verify a CMS SignedData structure + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags); + + STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms); + +=head1 DESCRIPTION + +CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo +structure to verify. B<certs> is a set of certificates in which to search for +the signing certificate(s). B<store> is a trusted certificate store used for +chain verification. B<indata> is the detached content if the content is not +present in B<cms>. The content is written to B<out> if it is not NULL. + +B<flags> is an optional set of flags, which can be used to modify the verify +operation. + +CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must +be called after a successful CMS_verify() operation. + +=head1 VERIFY PROCESS + +Normally the verify process proceeds as follows. + +Initially some sanity checks are performed on B<cms>. The type of B<cms> must +be SignedData. There must be at least one signature on the data and if +the content is detached B<indata> cannot be B<NULL>. + +An attempt is made to locate all the signing certificate(s), first looking in +the B<certs> parameter (if it is not NULL) and then looking in any +certificates contained in the B<cms> structure itself. If any signing +certificate cannot be located the operation fails. + +Each signing certificate is chain verified using the B<smimesign> purpose and +the supplied trusted certificate store. Any internal certificates in the message +are used as untrusted CAs. If CRL checking is enabled in B<store> any internal +CRLs are used in addition to attempting to look them up in B<store>. If any +chain verify fails an error code is returned. + +Finally the signed content is read (and written to B<out> is it is not NULL) +and the signature's checked. + +If all signature's verify correctly then the function is successful. + +Any of the following flags (ored together) can be passed in the B<flags> +parameter to change the default verify behaviour. + +If B<CMS_NOINTERN> is set the certificates in the message itself are not +searched when locating the signing certificate(s). This means that all the +signing certificates must be in the B<certs> parameter. + +If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any +CRLs in the message itself are ignored. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted +from the content. If the content is not of type B<text/plain> then an error is +returned. + +If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not +verified. + +If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not +verified. + +If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. + +=head1 NOTES + +One application of B<CMS_NOINTERN> is to only accept messages signed by +a small number of certificates. The acceptable certificates would be passed +in the B<certs> parameter. In this case if the signer is not one of the +certificates supplied in B<certs> then the verify will fail because the +signer cannot be found. + +In some cases the standard techniques for looking up and validating +certificates are not appropriate: for example an application may wish to +lookup certificates in a database or perform customised verification. This +can be achieved by setting and verifying the signers certificates manually +using the signed data utility functions. + +Care should be taken when modifying the default verify behaviour, for example +setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification +and any modified content will be considered valid. This combination is however +useful if one merely wishes to write the content to B<out> and its validity +is not considered important. + +Chain verification should arguably be performed using the signing time rather +than the current time. However since the signing time is supplied by the +signer it cannot be trusted without additional evidence (such as a trusted +timestamp). + +=head1 RETURN VALUES + +CMS_verify() returns 1 for a successful verification and zero if an error +occurred. + +CMS_get0_signers() returns all signers or NULL if an error occurred. + +The error can be obtained from L<ERR_get_error(3)> + +=head1 BUGS + +The trusted certificate store is not searched for the signing certificate, +this is primarily due to the inadequacies of the current B<X509_STORE> +functionality. + +The lack of single pass processing means that the signed content must all +be held in memory if it is not detached. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_sign(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CMS_verify_receipt.pod b/openssl-1.1.0h/doc/crypto/CMS_verify_receipt.pod new file mode 100644 index 0000000..193241c --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CMS_verify_receipt.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +CMS_verify_receipt - verify a CMS signed receipt + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int CMS_verify_receipt(CMS_ContentInfo *rcms, CMS_ContentInfo *ocms, STACK_OF(X509) *certs, X509_STORE *store, unsigned int flags); + +=head1 DESCRIPTION + +CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed +receipt to verify. B<ocms> is the original SignedData structure containing the +receipt request. B<certs> is a set of certificates in which to search for the +signing certificate. B<store> is a trusted certificate store (used for chain +verification). + +B<flags> is an optional set of flags, which can be used to modify the verify +operation. + +=head1 NOTES + +This functions behaves in a similar way to CMS_verify() except the flag values +B<CMS_DETACHED>, B<CMS_BINARY>, B<CMS_TEXT> and B<CMS_STREAM> are not +supported since they do not make sense in the context of signed receipts. + +=head1 RETURN VALUES + +CMS_verify_receipt() returns 1 for a successful verification and zero if an +error occurred. + +The error can be obtained from L<ERR_get_error(3)> + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<CMS_sign_receipt(3)>, +L<CMS_verify(3)>, + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CONF_modules_free.pod b/openssl-1.1.0h/doc/crypto/CONF_modules_free.pod new file mode 100644 index 0000000..ac59f37 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CONF_modules_free.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +CONF_modules_free, CONF_modules_finish, CONF_modules_unload - +OpenSSL configuration cleanup functions + +=head1 SYNOPSIS + + #include <openssl/conf.h> + + void CONF_modules_finish(void); + void CONF_modules_unload(int all); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + void CONF_modules_free(void) + #endif + +=head1 DESCRIPTION + +CONF_modules_free() closes down and frees up all memory allocated by all +configuration modules. + +CONF_modules_finish() calls each configuration modules B<finish> handler +to free up any configuration that module may have performed. + +CONF_modules_unload() finishes and unloads configuration modules. If +B<all> is set to B<0> only modules loaded from DSOs will be unloads. If +B<all> is B<1> all modules, including builtin modules will be unloaded. + +=head1 NOTES + +Normally in versions of OpenSSL prior to 1.1.0 applications will only call +CONF_modules_free() at application exit to tidy up any configuration performed. +From 1.1.0 CONF_modules_free() is deprecated and no explicit CONF cleanup is +required at all. For more information see L<OPENSSL_init_crypto(3)>. + +=head1 RETURN VALUE + +None of the functions return a value. + +=head1 SEE ALSO + +L<conf(5)>, L<OPENSSL_config(3)>, +L<CONF_modules_load_file(3)> + +=head1 HISTORY + +CONF_modules_free() was deprecated in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CONF_modules_load_file.pod b/openssl-1.1.0h/doc/crypto/CONF_modules_load_file.pod new file mode 100644 index 0000000..4f02f52 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CONF_modules_load_file.pod @@ -0,0 +1,135 @@ +=pod + +=head1 NAME + +CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions + +=head1 SYNOPSIS + + #include <openssl/conf.h> + + int CONF_modules_load_file(const char *filename, const char *appname, + unsigned long flags); + int CONF_modules_load(const CONF *cnf, const char *appname, + unsigned long flags); + +=head1 DESCRIPTION + +The function CONF_modules_load_file() configures OpenSSL using file +B<filename> and application name B<appname>. If B<filename> is NULL +the standard OpenSSL configuration file is used. If B<appname> is +NULL the standard OpenSSL application name B<openssl_conf> is used. +The behaviour can be customized using B<flags>. + +CONF_modules_load() is identical to CONF_modules_load_file() except it +reads configuration information from B<cnf>. + +=head1 NOTES + +The following B<flags> are currently recognized: + +B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual +configuration modules are ignored. If not set the first module error is +considered fatal and no further modules are loaded. + +Normally any modules errors will add error information to the error queue. If +B<CONF_MFLAGS_SILENT> is set no error information is added. + +If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is +disabled. + +B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file() +ignore missing configuration files. Normally a missing configuration file +return an error. + +B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the +default section pointed to by B<openssl_conf> if B<appname> does not exist. + +By using CONF_modules_load_file() with appropriate flags an application can +customise application configuration to best suit its needs. In some cases the +use of a configuration file is optional and its absence is not an error: in +this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set. + +Errors during configuration may also be handled differently by different +applications. For example in some cases an error may simply print out a warning +message and the application continue. In other cases an application might +consider a configuration file error as fatal and exit immediately. + +Applications can use the CONF_modules_load() function if they wish to load a +configuration file themselves and have finer control over how errors are +treated. + +=head1 EXAMPLES + +Load a configuration file and print out any errors and exit (missing file +considered fatal): + + if (CONF_modules_load_file(NULL, NULL, 0) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + +Load default configuration file using the section indicated by "myapp", +tolerate missing files, but exit on other errors: + + if (CONF_modules_load_file(NULL, "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + +Load custom configuration file and section, only print warnings on error, +missing configuration file ignored: + + if (CONF_modules_load_file("/something/app.cnf", "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "WARNING: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + } + +Load and parse configuration file manually, custom error handling: + + FILE *fp; + CONF *cnf = NULL; + long eline; + fp = fopen("/somepath/app.cnf", "r"); + if (fp == NULL) { + fprintf(stderr, "Error opening configuration file\n"); + /* Other missing configuration file behaviour */ + } else { + cnf = NCONF_new(NULL); + if (NCONF_load_fp(cnf, fp, &eline) == 0) { + fprintf(stderr, "Error on line %ld of configuration file\n", eline); + ERR_print_errors_fp(stderr); + /* Other malformed configuration file behaviour */ + } else if (CONF_modules_load(cnf, "appname", 0) <= 0) { + fprintf(stderr, "Error configuring application\n"); + ERR_print_errors_fp(stderr); + /* Other configuration error behaviour */ + } + fclose(fp); + NCONF_free(cnf); + } + +=head1 RETURN VALUES + +These functions return 1 for success and a zero or negative value for +failure. If module errors are not ignored the return code will reflect the +return value of the failing module (this will always be zero or negative). + +=head1 SEE ALSO + +L<config(5)>, L<OPENSSL_config(3)> + +=head1 COPYRIGHT + +Copyright 2004-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CRYPTO_THREAD_run_once.pod b/openssl-1.1.0h/doc/crypto/CRYPTO_THREAD_run_once.pod new file mode 100644 index 0000000..b256a18 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CRYPTO_THREAD_run_once.pod @@ -0,0 +1,170 @@ +=pod + +=head1 NAME + +CRYPTO_THREAD_run_once, +CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock, +CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL thread support + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT; + int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void)); + + CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void); + int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock); + int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock); + int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock); + void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock); + + int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock); + +=head1 DESCRIPTION + +OpenSSL can be safely used in multi-threaded applications provided that +support for the underlying OS threading API is built-in. Currently, OpenSSL +supports the pthread and Windows APIs. OpenSSL can also be built without +any multi-threading support, for example on platforms that don't provide +any threading support or that provide a threading API that is not yet +supported by OpenSSL. + +The following multi-threading function are provided: + +=over 2 + +=item * + +CRYPTO_THREAD_run_once() can be used to perform one-time initialization. +The B<once> argument must be a pointer to a static object of type +B<CRYPTO_ONCE> that was statically initialized to the value +B<CRYPTO_ONCE_STATIC_INIT>. +The B<init> argument is a pointer to a function that performs the desired +exactly once initialization. +In particular, this can be used to allocate locks in a thread-safe manner, +which can then be used with the locking functions below. + +=item * + +CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write +lock. + +=item * + +CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading. + +=item * + +CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing. + +=item * + +CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>. + +=item * + +CRYPTO_THREAD_lock_frees() frees the provided B<lock>. + +=item * + +CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the +result of the operation in B<ret>. B<lock> will be locked, unless atomic +operations are supported on the specific platform. Because of this, if a +variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must +be the only way that the variable is modified. + +=back + +=head1 RETURN VALUES + +CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error. + +CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error. + +CRYPTO_THREAD_lock_frees() returns no value. + +The other functions return 1 on success or 0 on error. + +=head1 NOTES + +On Windows platforms the CRYPTO_THREAD_* types and functions in the +openssl/crypto.h header are dependent on some of the types customarily +made available by including windows.h. The application developer is +likely to require control over when the latter is included, commonly as +one of the first included headers. Therefore it is defined as an +application developer's responsibility to include windows.h prior to +crypto.h where use of CRYPTO_THREAD_* types and functions is required. + +=head1 EXAMPLE + +This example safely initializes and uses a lock. + + #ifdef _WIN32 + # include <windows.h> + #endif + #include <openssl/crypto.h> + + static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT; + static CRYPTO_RWLOCK *lock; + + static void myinit(void) + { + lock = CRYPTO_THREAD_lock_new(); + } + + static int mylock(void) + { + if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL) + return 0; + return CRYPTO_THREAD_write_lock(lock); + } + + static int myunlock(void) + { + return CRYPTO_THREAD_unlock(lock); + } + + int serialized(void) + { + int ret = 0; + + if (mylock()) { + /* Your code here, do not return without releasing the lock! */ + ret = ... ; + } + myunlock(); + return ret; + } + +Finalization of locks is an advanced topic, not covered in this example. +This can only be done at process exit or when a dynamically loaded library is +no longer in use and is unloaded. +The simplest solution is to just "leak" the lock in applications and not +repeatedly load/unload shared libraries that allocate locks. + +=head1 NOTES + +You can find out if OpenSSL was configured with thread support: + + #include <openssl/opensslconf.h> + #if defined(OPENSSL_THREADS) + // thread support enabled + #else + // no thread support + #endif + +=head1 SEE ALSO + +L<crypto(7)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CRYPTO_get_ex_new_index.pod b/openssl-1.1.0h/doc/crypto/CRYPTO_get_ex_new_index.pod new file mode 100644 index 0000000..a5bf620 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CRYPTO_get_ex_new_index.pod @@ -0,0 +1,166 @@ +=pod + +=head1 NAME + +CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup, +CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data, +CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data +- functions supporting application-specific data + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + int CRYPTO_get_ex_new_index(int class_index, + long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + typedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from, + void *from_d, int idx, long argl, void *argp); + + int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad) + + int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); + + void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); + + void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r); + + int CRYPTO_free_ex_index(int class_index, int idx); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application-specific data attached to them, +known as "exdata." +The specific structures are: + + SSL + SSL_CTX + SSL_SESSION + X509 + X509_STORE + X509_STORE_CTX + DH + DSA + EC_KEY + RSA + ENGINE + UI + UI_METHOD + BIO + +Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h> +header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for +applications to use this facility for their own structures. + +The API described here is used by OpenSSL to manipulate exdata for specific +structures. Since the application data can be anything at all it is passed +and retrieved as a B<void *> type. + +The B<CRYPTO_EX_DATA> type is opaque. To initialize the exdata part of +a structure, call CRYPTO_new_ex_data(). This is only necessary for +B<CRYPTO_EX_INDEX_APP> objects. + +Exdata types are identified by an B<index>, an integer guaranteed to be +unique within structures for the lifetime of the program. Applications +using exdata typically call B<CRYPTO_get_ex_new_index> at startup, and +store the result in a global variable, or write a wrapper function to +provide lazy evaluation. The B<class_index> should be one of the +B<CRYPTO_EX_INDEX_xxx> values. The B<argl> and B<argp> parameters are saved +to be passed to the callbacks but are otherwise not used. In order to +transparently manipulate exdata, three callbacks must be provided. The +semantics of those callbacks are described below. + +When copying or releasing objects with exdata, the callback functions +are called in increasing order of their B<index> value. + +If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index() +when this is done. +This will replace the callbacks with no-ops +so that applications don't crash. Any existing exdata will be leaked. + +To set or get the exdata on an object, the appropriate type-specific +routine must be used. This is because the containing structure is opaque +and the B<CRYPTO_EX_DATA> field is not accessible. In both API's, the +B<idx> parameter should be an already-created index value. + +When setting exdata, the pointer specified with a particular index is saved, +and returned on a subsequent "get" call. If the application is going to +release the data, it must make sure to set a B<NULL> value at the index, +to avoid likely double-free crashes. + +The function B<CRYPTO_free_ex_data> is used to free all exdata attached +to a structure. The appropriate type-specific routine must be used. +The B<class_index> identifies the structure type, the B<obj> is +be the pointer to the actual structure, and B<r> is a pointer to the +structure's exdata field. + +=head2 Callback Functions + +This section describes how the callback functions are used. Applications +that are defining their own exdata using B<CYPRTO_EX_INDEX_APP> must +call them as described here. + +When a structure is initially allocated (such as RSA_new()) then the +new_func() is called for every defined index. There is no requirement +that the entire parent, or containing, structure has been set up. +The new_func() is typically used only to allocate memory to store the +exdata, and perhaps an "initialized" flag within that memory. +The exdata value should be set by calling CRYPTO_set_ex_data(). + +When a structure is free'd (such as SSL_CTX_free()) then the +free_func() is called for every defined index. Again, the state of the +parent structure is not guaranteed. The free_func() may be called with a +NULL pointer. + +Both new_func() and free_func() take the same parameters. +The B<parent> is the pointer to the structure that contains the exdata. +The B<ptr> is the current exdata item; for new_func() this will typically +be NULL. The B<r> parameter is a pointer to the exdata field of the object. +The B<idx> is the index and is the value returned when the callbacks were +initially registered via CRYPTO_get_ex_new_index() and can be used if +the same callback handles different types of exdata. + +dup_func() is called when a structure is being copied. This is only done +for B<SSL>, B<SSL_SESSION>, B<EC_KEY> objects and B<BIO> chains via +BIO_dup_chain(). The B<to> and B<from> parameters +are pointers to the destination and source B<CRYPTO_EX_DATA> structures, +respectively. The B<from_d> parameter needs to be cast to a B<void **pptr> +as the API has currently the wrong signature; that will be changed in a +future version. The B<*pptr> is a pointer to the source exdata. +When the dup_func() returns, the value in B<*pptr> is copied to the +destination ex_data. If the pointer contained in B<*pptr> is not modified +by the dup_func(), then both B<to> and B<from> will point to the same data. +The B<idx>, B<argl> and B<argp> parameters are as described for the other +two callbacks. If the dup_func() returns B<0> the whole CRYPTO_dup_ex_data() +will fail. + +=head1 RETURN VALUES + +CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the +value B<0> is reserved for the legacy "app_data" API's. + +CRYPTO_free_ex_index() and +CRYPTO_set_ex_data() return 1 on success or 0 on failure. + +CRYPTO_get_ex_data() returns the application data or NULL on failure; +note that NULL may be a valid value. + +dup_func() should return 0 for failure and 1 for success. + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CTLOG_STORE_get0_log_by_id.pod b/openssl-1.1.0h/doc/crypto/CTLOG_STORE_get0_log_by_id.pod new file mode 100644 index 0000000..c517e95 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CTLOG_STORE_get0_log_by_id.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +CTLOG_STORE_get0_log_by_id - +Get a Certificate Transparency log from a CTLOG_STORE + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + const CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store, + const uint8_t *log_id, + size_t log_id_len); + +=head1 DESCRIPTION + +A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency +(CT) log that issued it using the log's LogID (see RFC 6962, Section 3.2). +Therefore, it is useful to be able to look up more information about a log +(e.g. its public key) using this LogID. + +CTLOG_STORE_get0_log_by_id() provides a way to do this. It will find a CTLOG +in a CTLOG_STORE that has a given LogID. + +=head1 RETURN VALUES + +B<CTLOG_STORE_get0_log_by_id> returns a CTLOG with the given LogID, if it +exists in the given CTLOG_STORE, otherwise it returns NULL. + +=head1 SEE ALSO + +L<ct(3)>, +L<CTLOG_STORE_new(3)> + +=head1 HISTORY + +This function was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CTLOG_STORE_new.pod b/openssl-1.1.0h/doc/crypto/CTLOG_STORE_new.pod new file mode 100644 index 0000000..2a38f26 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CTLOG_STORE_new.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +CTLOG_STORE_new, CTLOG_STORE_free, +CTLOG_STORE_load_default_file, CTLOG_STORE_load_file - +Create and populate a Certificate Transparency log list + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + CTLOG_STORE *CTLOG_STORE_new(void); + void CTLOG_STORE_free(CTLOG_STORE *store); + + int CTLOG_STORE_load_default_file(CTLOG_STORE *store); + int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file); + +=head1 DESCRIPTION + +A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency +logs). The list can be loaded from one or more files and then searched by LogID +(see RFC 6962, Section 3.2, for the definition of a LogID). + +CTLOG_STORE_new() creates an empty list of CT logs. This is then populated +by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file(). +CTLOG_STORE_load_default_file() loads from the default file, which is named +"ct_log_list.cnf" in OPENSSLDIR (see the output of L<version>). This can be +overridden using an environment variable named "CTLOG_FILE". +CTLOG_STORE_load_file() loads from a caller-specified file path instead. +Both of these functions append any loaded CT logs to the CTLOG_STORE. + +The expected format of the file is: + + enabled_logs=foo,bar + + [foo] + description = Log 1 + key = <base64-encoded DER SubjectPublicKeyInfo here> + + [bar] + description = Log 2 + key = <base64-encoded DER SubjectPublicKeyInfo here> + +Once a CTLOG_STORE is no longer required, it should be passed to +CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along +with the CTLOG_STORE itself. + +=head1 NOTES + +If there are any invalid CT logs in a file, they are skipped and the remaining +valid logs will still be added to the CTLOG_STORE. A CT log will be considered +invalid if it is missing a "key" or "description" field. + +=head1 RETURN VALUES + +Both B<CTLOG_STORE_load_default_file> and B<CTLOG_STORE_load_file> return 1 if +all CT logs in the file are successfully parsed and loaded, 0 otherwise. + +=head1 SEE ALSO + +L<ct(3)>, +L<CTLOG_STORE_get0_log_by_id(3)>, +L<SSL_CTX_set_ctlog_list_file(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CTLOG_new.pod b/openssl-1.1.0h/doc/crypto/CTLOG_new.pod new file mode 100644 index 0000000..ccda6b9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CTLOG_new.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +CTLOG_new, CTLOG_new_from_base64, CTLOG_free, +CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key - +encapsulates information about a Certificate Transparency log + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name); + int CTLOG_new_from_base64(CTLOG ** ct_log, + const char *pkey_base64, const char *name); + void CTLOG_free(CTLOG *log); + const char *CTLOG_get0_name(const CTLOG *log); + void CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id, + size_t *log_id_len); + EVP_PKEY *CTLOG_get0_public_key(const CTLOG *log); + +=head1 DESCRIPTION + +CTLOG_new() returns a new CTLOG that represents the Certificate Transparency +(CT) log with the given public key. A name must also be provided that can be +used to help users identify this log. Ownership of the public key is +transferred. + +CTLOG_new_from_base64() also creates a new CTLOG, but takes the public key in +base64-encoded DER form and sets the ct_log pointer to point to the new CTLOG. +The base64 will be decoded and the public key parsed. + +Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the +caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer +needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that +was passed to it. + +CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was +created. Ownership of the string remains with the CTLOG. + +CTLOG_get0_log_id() sets *log_id to point to a string containing that log's +LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a +v1 CT log, the LogID will be a SHA-256 hash (i.e. 32 bytes long). Ownership of +the string remains with the CTLOG. + +CTLOG_get0_public_key() returns the public key of the CT log. Ownership of the +EVP_PKEY remains with the CTLOG. + +=head1 RETURN VALUES + +CTLOG_new() will return NULL if an error occurs. + +CTLOG_new_from_base64() will return 1 on success, 0 otherwise. + +=head1 SEE ALSO + +L<ct(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/CT_POLICY_EVAL_CTX_new.pod b/openssl-1.1.0h/doc/crypto/CT_POLICY_EVAL_CTX_new.pod new file mode 100644 index 0000000..7839fd3 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CT_POLICY_EVAL_CTX_new.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, +CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, +CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, +CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE, +CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time - +Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void); + void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx); + X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx); + int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert); + X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx); + int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer); + const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx); + void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store); + uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx); + void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms); + +=head1 DESCRIPTION + +A B<CT_POLICY_EVAL_CTX> is used by functions that evaluate whether Signed +Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy. +This policy may be, for example, that at least one valid SCT is available. To +determine this, an SCT's timestamp and signature must be verified. +This requires: + +=over 4 + +=item * the public key of the log that issued the SCT + +=item * the certificate that the SCT was issued for + +=item * the issuer certificate (if the SCT was issued for a pre-certificate) + +=item * the current time + +=back + +The above requirements are met using the setters described below. + +CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This +should then be populated using: + +=over 4 + +=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for + +Increments the reference count of the certificate. + +=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate + +Increments the reference count of the certificate. + +=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs + +Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the +CT_POLICY_EVAL_CTX. + +=item * CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid + +The SCT timestamp will be compared to this time to check whether the SCT was +issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose +timestamp is in the future". By default, this will be set to 5 minutes in the +future (e.g. (time() + 300) * 1000), to allow for clock drift. + +The time should be in milliseconds since the Unix epoch. + +=back + +Each setter has a matching getter for accessing the current value. + +When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to +CT_POLICY_EVAL_CTX_free() to delete it. + +=head1 NOTES + +The issuer certificate only needs to be provided if at least one of the SCTs +was issued for a pre-certificate. This will be the case for SCTs embedded in a +certificate (i.e. those in an X.509 extension), but may not be the case for SCTs +found in the TLS SCT extension or OCSP response. + +=head1 RETURN VALUES + +CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails. + +=head1 SEE ALSO + +L<ct(7)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DEFINE_STACK_OF.pod b/openssl-1.1.0h/doc/crypto/DEFINE_STACK_OF.pod new file mode 100644 index 0000000..f655f84 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DEFINE_STACK_OF.pod @@ -0,0 +1,241 @@ +=pod + +=head1 NAME + +DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF, +DEFINE_SPECIAL_STACK_OF_CONST, +OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr, +OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free, +OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null, +OPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push, +OPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort, +OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero, +sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_free, +sk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push, +sk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free, +sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort, +sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func - +stack container + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/safestack.h> + + STACK_OF(TYPE) + DEFINE_STACK_OF(TYPE) + DEFINE_STACK_OF_CONST(TYPE) + DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE) + DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE) + + typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b); + typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a); + typedef void (*sk_TYPE_freefunc)(TYPE *a); + + int sk_TYPE_num(const STACK_OF(TYPE) *sk); + TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx); + STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare); + STACK_OF(TYPE) *sk_TYPE_new_null(void); + void sk_TYPE_free(const STACK_OF(TYPE) *sk); + void sk_TYPE_zero(const STACK_OF(TYPE) *sk); + TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i); + TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr); + int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr); + int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr); + TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk); + TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk); + void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc); + int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx); + TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr); + int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr); + int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr); + void sk_TYPE_sort(const STACK_OF(TYPE) *sk); + int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk); + STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk); + STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk, + sk_TYPE_copyfunc copyfunc, + sk_TYPE_freefunc freefunc); + sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk, sk_TYPE_compfunc compare); + +=head1 DESCRIPTION + +Applications can create and use their own stacks by placing any of the macros +described below in a header file. These macros define typesafe inline +functions that wrap around the utility B<OPENSSL_sk_> API. +In the description here, I<TYPE> is used +as a placeholder for any of the OpenSSL datatypes, such as I<X509>. + +STACK_OF() returns the name for a stack of the specified B<TYPE>. +DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This +will mean that type B<TYPE> is stored in each stack, the type is referenced by +STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example: + + TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); + +DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except +each element is constant. For example: + + const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); + +DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but +each function uses B<FUNCNAME> in the function name. For example: + + TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); + +DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is +constant: + + const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); + +sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is +B<NULL>. + +sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at +zero. If B<idx> is out of range then B<NULL> is returned. + +sk_TYPE_new() allocates a new empty stack using comparison function B<compare>. +If B<compare> is B<NULL> then no comparison function is used. + +sk_TYPE_new_null() allocates a new empty stack with no comparison function. + +sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compare>. +The previous comparison function is returned or B<NULL> if there was +no previous comparison function. + +sk_TYPE_free() frees up the B<sk> structure. It does B<not> free up any +elements of B<sk>. After this call B<sk> is no longer valid. + +sk_TYPE_zero() sets the number of elements in B<sk> to zero. It does not free +B<sk> so after this call B<sk> is still valid. + +sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The +free function freefunc() is called on each element to free it. + +sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted +element or B<NULL> if B<i> is out of range. + +sk_TYPE_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns +the deleted element or B<NULL> if no element matching B<ptr> was found. + +sk_TYPE_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing +elements at or after B<idx> are moved downwards. If B<idx> is out of range +the new element is appended to B<sk>. sk_TYPE_insert() either returns the +number of elements in B<sk> after the new element is inserted or zero if +an error (such as memory allocation failure) occurred. + +sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to: + + sk_TYPE_insert(sk, ptr, -1); + +sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to: + + sk_TYPE_insert(sk, ptr, 0); + +sk_TYPE_pop() returns and removes the last element from B<sk>. + +sk_TYPE_shift() returns and removes the first element from B<sk>. + +sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current +element. The new element value is returned or B<NULL> if an error occurred: +this will only happen if B<sk> is B<NULL> or B<idx> is out of range. + +sk_TYPE_find() searches B<sk> for the element B<ptr>. In the case +where no comparison function has been specified, the function performs +a linear search for a pointer equal to B<ptr>. The index of the first +matching element is returned or B<-1> if there is no match. In the case +where a comparison function has been specified, B<sk> is sorted then +sk_TYPE_find() returns the index of a matching element or B<-1> if there +is no match. Note that, in this case, the matching element returned is +not guaranteed to be the first; the comparison function will usually +compare the values pointed to rather than the pointers themselves and +the order of elements in B<sk> could change. + +sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison +function has been specified and no matching element is found. Instead +of returning B<-1>, sk_TYPE_find_ex() returns the index of the element +either before or after the location where B<ptr> would be if it were +present in B<sk>. + +sk_TYPE_sort() sorts B<sk> using the supplied comparison function. + +sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise. + +sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy +are identical to the original. + +sk_TYPE_deep_copy() returns a new stack where each element has been copied. +Copying is performed by the supplied copyfunc() and freeing by freefunc(). The +function freefunc() is only called if an error occurs. + +=head1 NOTES + +Care should be taken when accessing stacks in multi-threaded environments. +Any operation which increases the size of a stack such as sk_TYPE_insert() or +sk_push() can "grow" the size of an internal array and cause race conditions +if the same stack is accessed in a different thread. Operations such as +sk_find() and sk_sort() can also reorder the stack. + +Any comparison function supplied should use a metric suitable +for use in a binary search operation. That is it should return zero, a +positive or negative value if B<a> is equal to, greater than +or less than B<b> respectively. + +Care should be taken when checking the return values of the functions +sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the +matching element. In particular B<0> indicates a matching first element. +A failed search is indicated by a B<-1> return value. + +STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and +DEFINE_SPECIAL_STACK_OF() are implemented as macros. + +=head1 RETURN VALUES + +sk_TYPE_num() returns the number of elements in the stack or B<-1> if the +passed stack is B<NULL>. + +sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the +index is out of range. + +sk_TYPE_new() and sk_TYPE_new_null() return an empty stack or B<NULL> if +an error occurs. + +sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if +there was no old comparison function. + +sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do +not return values. + +sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr() +return a pointer to the deleted element or B<NULL> on error. + +sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total +number of elements in the stack and 0 if an error occurred. + +sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on +error. + +sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element +or B<-1> on error. + +sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is +not. + +sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the +stack. + +=head1 HISTORY + +Before OpenSSL 1.1.0, this was implemented via macros and not inline functions +and was not a public API. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DES_random_key.pod b/openssl-1.1.0h/doc/crypto/DES_random_key.pod new file mode 100644 index 0000000..77cfdda --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DES_random_key.pod @@ -0,0 +1,310 @@ +=pod + +=head1 NAME + +DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, +DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, +DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, +DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, +DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, +DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, +DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, +DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, +DES_fcrypt, DES_crypt - DES encryption + +=head1 SYNOPSIS + + #include <openssl/des.h> + + void DES_random_key(DES_cblock *ret); + + int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule); + int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule); + int DES_set_key_checked(const_DES_cblock *key, + DES_key_schedule *schedule); + void DES_set_key_unchecked(const_DES_cblock *key, + DES_key_schedule *schedule); + + void DES_set_odd_parity(DES_cblock *key); + int DES_is_weak_key(const_DES_cblock *key); + + void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, + DES_key_schedule *ks, int enc); + void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, + DES_key_schedule *ks1, DES_key_schedule *ks2, int enc); + void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, + DES_key_schedule *ks1, DES_key_schedule *ks2, + DES_key_schedule *ks3, int enc); + + void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, + long length, DES_key_schedule *schedule, DES_cblock *ivec, + int enc); + void DES_cfb_encrypt(const unsigned char *in, unsigned char *out, + int numbits, long length, DES_key_schedule *schedule, + DES_cblock *ivec, int enc); + void DES_ofb_encrypt(const unsigned char *in, unsigned char *out, + int numbits, long length, DES_key_schedule *schedule, + DES_cblock *ivec); + void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, + long length, DES_key_schedule *schedule, DES_cblock *ivec, + int enc); + void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out, + long length, DES_key_schedule *schedule, DES_cblock *ivec, + int *num, int enc); + void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out, + long length, DES_key_schedule *schedule, DES_cblock *ivec, + int *num); + + void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, + long length, DES_key_schedule *schedule, DES_cblock *ivec, + const_DES_cblock *inw, const_DES_cblock *outw, int enc); + + void DES_ede2_cbc_encrypt(const unsigned char *input, + unsigned char *output, long length, DES_key_schedule *ks1, + DES_key_schedule *ks2, DES_cblock *ivec, int enc); + void DES_ede2_cfb64_encrypt(const unsigned char *in, + unsigned char *out, long length, DES_key_schedule *ks1, + DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc); + void DES_ede2_ofb64_encrypt(const unsigned char *in, + unsigned char *out, long length, DES_key_schedule *ks1, + DES_key_schedule *ks2, DES_cblock *ivec, int *num); + + void DES_ede3_cbc_encrypt(const unsigned char *input, + unsigned char *output, long length, DES_key_schedule *ks1, + DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec, + int enc); + void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, + long length, DES_key_schedule *ks1, DES_key_schedule *ks2, + DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc); + void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, + long length, DES_key_schedule *ks1, + DES_key_schedule *ks2, DES_key_schedule *ks3, + DES_cblock *ivec, int *num); + + DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, + long length, DES_key_schedule *schedule, + const_DES_cblock *ivec); + DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], + long length, int out_count, DES_cblock *seed); + void DES_string_to_key(const char *str, DES_cblock *key); + void DES_string_to_2keys(const char *str, DES_cblock *key1, + DES_cblock *key2); + + char *DES_fcrypt(const char *buf, const char *salt, char *ret); + char *DES_crypt(const char *buf, const char *salt); + +=head1 DESCRIPTION + +This library contains a fast implementation of the DES encryption +algorithm. + +There are two phases to the use of DES encryption. The first is the +generation of a I<DES_key_schedule> from a key, the second is the +actual encryption. A DES key is of type I<DES_cblock>. This type is +consists of 8 bytes with odd parity. The least significant bit in +each byte is the parity bit. The key schedule is an expanded form of +the key; it is used to speed the encryption process. + +DES_random_key() generates a random key. The PRNG must be seeded +prior to using this function (see L<rand(3)>). If the PRNG +could not generate a secure key, 0 is returned. + +Before a DES key can be used, it must be converted into the +architecture dependent I<DES_key_schedule> via the +DES_set_key_checked() or DES_set_key_unchecked() function. + +DES_set_key_checked() will check that the key passed is of odd parity +and is not a weak or semi-weak key. If the parity is wrong, then -1 +is returned. If the key is a weak key, then -2 is returned. If an +error is returned, the key schedule is not generated. + +DES_set_key() works like +DES_set_key_checked() if the I<DES_check_key> flag is non-zero, +otherwise like DES_set_key_unchecked(). These functions are available +for compatibility; it is recommended to use a function that does not +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 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. + +DES_ecb_encrypt() is the basic DES encryption routine that encrypts or +decrypts a single 8-byte I<DES_cblock> in I<electronic code book> +(ECB) mode. It always transforms the input data, pointed to by +I<input>, into the output data, pointed to by the I<output> argument. +If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input> +(cleartext) is encrypted in to the I<output> (ciphertext) using the +key_schedule specified by the I<schedule> argument, previously set via +I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now +ciphertext) is decrypted into the I<output> (now cleartext). Input +and output may overlap. DES_ecb_encrypt() does not return a value. + +DES_ecb3_encrypt() encrypts/decrypts the I<input> block by using +three-key Triple-DES encryption in ECB mode. This involves encrypting +the input with I<ks1>, decrypting with the key schedule I<ks2>, and +then encrypting with I<ks3>. This routine greatly reduces the chances +of brute force breaking of DES and has the advantage of if I<ks1>, +I<ks2> and I<ks3> are the same, it is equivalent to just encryption +using ECB mode and I<ks1> as the key. + +The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES +encryption by using I<ks1> for the final encryption. + +DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining> +(CBC) mode of DES. If the I<encrypt> argument is non-zero, the +routine cipher-block-chain encrypts the cleartext data pointed to by +the I<input> argument into the ciphertext pointed to by the I<output> +argument, using the key schedule provided by the I<schedule> argument, +and initialization vector provided by the I<ivec> argument. If the +I<length> argument is not an integral multiple of eight bytes, the +last block is copied to a temporary area and zero filled. The output +is always an integral multiple of eight bytes. + +DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses I<inw> and +I<outw> to 'whiten' the encryption. I<inw> and I<outw> are secret +(unlike the iv) and are as such, part of the key. So the key is sort +of 24 bytes. This is much better than CBC DES. + +DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with +three keys. This means that each DES operation inside the CBC mode is +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)))>. +This form of Triple-DES is used by the RSAREF library. + +DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block +chaining mode used by Kerberos v4. Its parameters are the same as +DES_ncbc_encrypt(). + +DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This +method takes an array of characters as input and outputs and array of +characters. It does not require any padding to 8 character groups. +Note: the I<ivec> variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete DES ECB encryption per I<numbits>, this function is only +suggested for use when sending small numbers of characters. + +DES_cfb64_encrypt() +implements CFB mode of DES with 64bit feedback. Why is this +useful you ask? Because this routine will allow you to encrypt an +arbitrary number of bytes, no 8 byte padding. Each call to this +routine will encrypt the input bytes to output and then update ivec +and num. num contains 'how far' we are though ivec. If this does +not make much sense, read more about cfb mode of DES :-). + +DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as +DES_cfb64_encrypt() except that Triple-DES is used. + +DES_ofb_encrypt() encrypts using output feedback mode. This method +takes an array of characters as input and outputs and array of +characters. It does not require any padding to 8 character groups. +Note: the I<ivec> variable is changed and the new changed value needs to +be passed to the next call to this function. Since this function runs +a complete DES ECB encryption per numbits, this function is only +suggested for use when sending small numbers of characters. + +DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output +Feed Back mode. + +DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as +DES_ofb64_encrypt(), using Triple-DES. + +The following functions are included in the DES library for +compatibility with the MIT Kerberos library. + +DES_cbc_cksum() produces an 8 byte checksum based on the input stream +(via CBC encryption). The last 4 bytes of the checksum are returned +and the complete 8 bytes are placed in I<output>. This function is +used by Kerberos v4. Other applications should use +L<EVP_DigestInit(3)> etc. instead. + +DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte +checksum from the input bytes. The algorithm can be iterated over the +input, depending on I<out_count>, 1, 2, 3 or 4 times. If I<output> is +non-NULL, the 8 bytes generated by each pass are written into +I<output>. + +The following are DES-based transformations: + +DES_fcrypt() is a fast version of the Unix crypt(3) function. This +version takes only a small amount of space relative to other fast +crypt() implementations. This is different to the normal crypt in +that the third parameter is the buffer that the return value is +written into. It needs to be at least 14 bytes long. This function +is thread safe, unlike the normal crypt. + +DES_crypt() is a faster replacement for the normal system crypt(). +This function calls DES_fcrypt() with a static array passed as the +third parameter. This mostly emulates the normal non-thread-safe semantics +of crypt(3). +The B<salt> must be two ASCII characters. + +DES_enc_write() writes I<len> bytes to file descriptor I<fd> from +buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default) +using I<sched> for the key and I<iv> as a starting vector. The actual +data send down I<fd> consists of 4 bytes (in network byte order) +containing the length of the following encrypted data. The encrypted +data then follows, padded with random data out to a multiple of 8 +bytes. + +=head1 BUGS + +DES_3cbc_encrypt() is flawed and must not be used in applications. + +DES_cbc_encrypt() does not modify B<ivec>; use DES_ncbc_encrypt() +instead. + +DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits. +What this means is that if you set numbits to 12, and length to 2, the +first 12 bits will come from the 1st input byte and the low half of +the second input byte. The second 12 bits will have the low 8 bits +taken from the 3rd input byte and the top 4 bits taken from the 4th +input byte. The same holds for output. This function has been +implemented this way because most people will be using a multiple of 8 +and because once you get into pulling bytes input bytes apart things +get ugly! + +DES_string_to_key() is available for backward compatibility with the +MIT library. New applications should use a cryptographic hash function. +The same applies for DES_string_to_2key(). + +=head1 NOTES + +The B<des> library was written to be source code compatible with +the MIT Kerberos library. + +Applications should use the higher level functions +L<EVP_EncryptInit(3)> etc. instead of calling these +functions directly. + +Single-key DES is insecure due to its short key size. ECB mode is +not suitable for most applications; see L<des_modes(7)>. + +=head1 HISTORY + +The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt() +be two ASCII characters was first enforced in +OpenSSL 1.1.0. Previous versions tried to use the letter uppercase B<A> +if both character were not present, and could crash when given non-ASCII +on some platforms. + +=head1 SEE ALSO + +L<des_modes(7)>, +L<EVP_EncryptInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DH_generate_key.pod b/openssl-1.1.0h/doc/crypto/DH_generate_key.pod new file mode 100644 index 0000000..de0847a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DH_generate_key.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + int DH_generate_key(DH *dh); + + int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); + +=head1 DESCRIPTION + +DH_generate_key() performs the first step of a Diffie-Hellman key +exchange by generating private and public DH values. By calling +DH_compute_key(), these are combined with the other party's public +value to compute the shared key. + +DH_generate_key() expects B<dh> to contain the shared parameters +B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value +unless B<dh-E<gt>priv_key> is already set, and computes the +corresponding public value B<dh-E<gt>pub_key>, which can then be +published. + +DH_compute_key() computes the shared secret from the private DH value +in B<dh> and the other party's public value in B<pub_key> and stores +it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory. + +=head1 RETURN VALUES + +DH_generate_key() returns 1 on success, 0 otherwise. + +DH_compute_key() returns the size of the shared secret on success, -1 +on error. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>, L<DH_size(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DH_generate_parameters.pod b/openssl-1.1.0h/doc/crypto/DH_generate_parameters.pod new file mode 100644 index 0000000..ce178af --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DH_generate_parameters.pod @@ -0,0 +1,134 @@ +=pod + +=head1 NAME + +DH_generate_parameters_ex, DH_generate_parameters, +DH_check, DH_check_params - generate and check Diffie-Hellman +parameters + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb); + + int DH_check(DH *dh, int *codes); + int DH_check_params(DH *dh, int *codes); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x00908000L + DH *DH_generate_parameters(int prime_len, int generator, + void (*callback)(int, int, void *), void *cb_arg); + #endif + +=head1 DESCRIPTION + +DH_generate_parameters_ex() generates Diffie-Hellman parameters that can +be shared among a group of users, and stores them in the provided B<DH> +structure. The pseudo-random number generator must be +seeded prior to calling DH_generate_parameters(). + +B<prime_len> is the length in bits of the safe prime to be generated. +B<generator> is a small number E<gt> 1, typically 2 or 5. + +A callback function may be used to provide feedback about the progress +of the key generation. If B<cb> is not B<NULL>, it will be +called as described in L<BN_generate_prime(3)> while a random prime +number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)> +is called. See L<BN_generate_prime(3)> for information on +the BN_GENCB_call() function. + +DH_check_params() confirms that the B<p> and B<g> are likely enough to +be valid. +This is a lightweight check, if a more thorough check is needed, use +DH_check(). +The value of B<*codes> is updated with any problems found. +If B<*codes> is zero then no problems were found, otherwise the +following bits may be set: + +=over 4 + +=item DH_CHECK_P_NOT_PRIME + +The parameter B<p> has been determined to not being an odd prime. +Note that the lack of this bit doesn't guarantee that B<p> is a +prime. + +=item DH_NOT_SUITABLE_GENERATOR + +The generator B<g> is not suitable. +Note that the lack of this bit doesn't guarantee that B<g> is +suitable, unless B<p> is known to be a strong prime. + +=back + +DH_check() confirms that the Diffie-Hellman parameters B<dh> are valid. The +value of B<*codes> is updated with any problems found. If B<*codes> is zero then +no problems were found, otherwise the following bits may be set: + +=over 4 + +=item DH_CHECK_P_NOT_PRIME + +The parameter B<p> is not prime. + +=item DH_CHECK_P_NOT_SAFE_PRIME + +The parameter B<p> is not a safe prime and no B<q> value is present. + +=item DH_UNABLE_TO_CHECK_GENERATOR + +The generator B<g> cannot be checked for suitability. + +=item DH_NOT_SUITABLE_GENERATOR + +The generator B<g> is not suitable. + +=item DH_CHECK_Q_NOT_PRIME + +The parameter B<q> is not prime. + +=item DH_CHECK_INVALID_Q_VALUE + +The parameter B<q> is invalid. + +=item DH_CHECK_INVALID_J_VALUE + +The parameter B<j> is invalid. + +=back + +=head1 RETURN VALUES + +DH_generate_parameters_ex(), DH_check() and DH_check_params() return 1 +if the check could be performed, 0 otherwise. + +DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or +NULL if the parameter generation fails. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 NOTES + +DH_generate_parameters_ex() and DH_generate_parameters() may run for several +hours before finding a suitable prime. + +The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters() +are not to be used in signature schemes. + +=head1 SEE ALSO + +L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, +L<DH_free(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DH_get0_pqg.pod b/openssl-1.1.0h/doc/crypto/DH_get0_pqg.pod new file mode 100644 index 0000000..3809813 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DH_get0_pqg.pod @@ -0,0 +1,110 @@ +=pod + +=head1 NAME + +DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, DH_clear_flags, +DH_test_flags, DH_set_flags, DH_get0_engine, DH_get_length, +DH_set_length - Routines for getting and setting data in a DH object + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + void DH_get0_pqg(const DH *dh, + const BIGNUM **p, const BIGNUM **q, const BIGNUM **g); + int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g); + void DH_get0_key(const DH *dh, + const BIGNUM **pub_key, const BIGNUM **priv_key); + int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key); + void DH_clear_flags(DH *dh, int flags); + int DH_test_flags(const DH *dh, int flags); + void DH_set_flags(DH *dh, int flags); + ENGINE *DH_get0_engine(DH *d); + long DH_get_length(const DH *dh); + int DH_set_length(DH *dh, long length); + +=head1 DESCRIPTION + +A DH object contains the parameters B<p>, B<q> and B<g>. Note that the B<q> +parameter is optional. It also contains a public key (B<pub_key>) and +(optionally) a private key (B<priv_key>). + +The B<p>, B<q> and B<g> parameters can be obtained by calling DH_get0_pqg(). +If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set +to NULL. Otherwise they are set to pointers to their respective values. These +point directly to the internal representations of the values and therefore +should not be freed directly. + +The B<p>, B<q> and B<g> values can be set by calling DH_set0_pqg() and passing +the new values for B<p>, B<q> and B<g> as parameters to the function. Calling +this function transfers the memory management of the values to the DH object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. The B<q> parameter may be NULL. + +To get the public and private key values use the DH_get0_key() function. A +pointer to the public key will be stored in B<*pub_key>, and a pointer to the +private key will be stored in B<*priv_key>. Either may be NULL if they have not +been set yet, although if the private key has been set then the public key must +be. The values point to the internal representation of the public key and +private key values. This memory should not be freed directly. + +The public and private key values can be set using DH_set0_key(). Either +parameter may be NULL, which means the corresponding DH field is left +untouched. As with DH_set0_pqg() this function transfers the memory management +of the key values to the DH object, and therefore they should not be freed +directly after this function has been called. + +DH_set_flags() sets the flags in the B<flags> parameter on the DH object. +Multiple flags can be passed in one go (bitwise ORed together). Any flags that +are already set are left set. DH_test_flags() tests to see whether the flags +passed in the B<flags> parameter are currently set in the DH object. Multiple +flags can be tested in one go. All flags that are currently set are returned, or +zero if none of the flags are set. DH_clear_flags() clears the specified flags +within the DH object. + +DH_get0_engine() returns a handle to the ENGINE that has been set for this DH +object, or NULL if no such ENGINE has been set. + +The DH_get_length() and DH_set_length() functions get and set the optional +length parameter associated with this DH object. If the length is non-zero then +it is used, otherwise it is ignored. The B<length> parameter indicates the +length of the secret exponent (private key) in bits. + +=head1 NOTES + +Values retrieved with DH_get0_key() are owned by the DH object used +in the call and may therefore I<not> be passed to DH_set0_key(). If +needed, duplicate the received value using BN_dup() and pass the +duplicate. The same applies to DH_get0_pqg() and DH_set0_pqg(). + +=head1 RETURN VALUES + +DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure. + +DH_test_flags() returns the current state of the flags in the DH object. + +DH_get0_engine() returns the ENGINE set for the DH object or NULL if no ENGINE +has been set. + +DH_get_length() returns the length of the secret exponent (private key) in bits, +or zero if no such length has been explicitly set. + +=head1 SEE ALSO + +L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>, +L<DH_set_method(3)>, L<DH_size(3)>, L<DH_meth_new(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DH_get_1024_160.pod b/openssl-1.1.0h/doc/crypto/DH_get_1024_160.pod new file mode 100644 index 0000000..4044f10 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DH_get_1024_160.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +DH_get_1024_160, +DH_get_2048_224, +DH_get_2048_256, +BN_get0_nist_prime_192, +BN_get0_nist_prime_224, +BN_get0_nist_prime_256, +BN_get0_nist_prime_384, +BN_get0_nist_prime_521, +BN_get_rfc2409_prime_768, +BN_get_rfc2409_prime_1024, +BN_get_rfc3526_prime_1536, +BN_get_rfc3526_prime_2048, +BN_get_rfc3526_prime_3072, +BN_get_rfc3526_prime_4096, +BN_get_rfc3526_prime_6144, +BN_get_rfc3526_prime_8192 +- Create standardized public primes or DH pairs + +=head1 SYNOPSIS + + #include <openssl/dh.h> + DH *DH_get_1024_160(void) + DH *DH_get_2048_224(void) + DH *DH_get_2048_256(void) + + const BIGNUM *BN_get0_nist_prime_192(void) + const BIGNUM *BN_get0_nist_prime_224(void) + const BIGNUM *BN_get0_nist_prime_256(void) + const BIGNUM *BN_get0_nist_prime_384(void) + const BIGNUM *BN_get0_nist_prime_521(void) + + BIGNUM *BN_get_rfc2409_prime_768(BIGNUM *bn) + BIGNUM *BN_get_rfc2409_prime_1024(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *bn) + +=head1 DESCRIPTION + +DH_get_1024_160(), DH_get_2048_224(), and DH_get_2048_256() each return +a DH object for the IETF RFC 5114 value. + +BN_get0_nist_prime_192(), BN_get0_nist_prime_224(), BN_get0_nist_prime_256(), +BN_get0_nist_prime_384(), and BN_get0_nist_prime_521() functions return +a BIGNUM for the specific NIST prime curve (e.g., P-256). + +BN_get_rfc2409_prime_768(), BN_get_rfc2409_prime_1024(), +BN_get_rfc3526_prime_1536(), BN_get_rfc3526_prime_2048(), +BN_get_rfc3526_prime_3072(), BN_get_rfc3526_prime_4096(), +BN_get_rfc3526_prime_6144(), and BN_get_rfc3526_prime_8192() functions +return a BIGNUM for the specified size from IETF RFC 2409. If B<bn> +is not NULL, the BIGNUM will be set into that location as well. + +=head1 RETURN VALUES + +Defined above. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DH_meth_new.pod b/openssl-1.1.0h/doc/crypto/DH_meth_new.pod new file mode 100644 index 0000000..d768da8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DH_meth_new.pod @@ -0,0 +1,156 @@ +=pod + +=head1 NAME + +DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name, +DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data, +DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key, +DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp, +DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish, +DH_meth_set_finish, DH_meth_get_generate_params, +DH_meth_set_generate_params - Routines to build up DH methods + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + DH_METHOD *DH_meth_new(const char *name, int flags); + void DH_meth_free(DH_METHOD *dhm); + DH_METHOD *DH_meth_dup(const DH_METHOD *dhm); + const char *DH_meth_get0_name(const DH_METHOD *dhm); + int DH_meth_set1_name(DH_METHOD *dhm, const char *name); + int DH_meth_get_flags(DH_METHOD *dhm); + int DH_meth_set_flags(DH_METHOD *dhm, int flags); + void *DH_meth_get0_app_data(const DH_METHOD *dhm); + int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data); + int (*DH_meth_get_generate_key(const DH_METHOD *dhm)) (DH *); + int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key) (DH *)); + int (*DH_meth_get_compute_key(const DH_METHOD *dhm)) + (unsigned char *key, const BIGNUM *pub_key, DH *dh); + int DH_meth_set_compute_key(DH_METHOD *dhm, + int (*compute_key) (unsigned char *key, const BIGNUM *pub_key, DH *dh)); + int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm)) + (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); + int DH_meth_set_bn_mod_exp(DH_METHOD *dhm, + int (*bn_mod_exp) (const DH *dh, BIGNUM *r, const BIGNUM *a, + const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, + BN_MONT_CTX *m_ctx)); + int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *); + int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *)); + int (*DH_meth_get_finish(const DH_METHOD *dhm)) (DH *); + int DH_meth_set_finish(DH_METHOD *dhm, int (*finish) (DH *)); + int (*DH_meth_get_generate_params(const DH_METHOD *dhm)) + (DH *, int, int, BN_GENCB *); + int DH_meth_set_generate_params(DH_METHOD *dhm, + int (*generate_params) (DH *, int, int, BN_GENCB *)); + +=head1 DESCRIPTION + +The B<DH_METHOD> type is a structure used for the provision of custom DH +implementations. It provides a set of of functions used by OpenSSL for the +implementation of the various DH capabilities. + +DH_meth_new() creates a new B<DH_METHOD> structure. It should be given a +unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated +string, which will be duplicated and stored in the B<DH_METHOD> object. It is +the callers responsibility to free the original string. The flags will be used +during the construction of a new B<DH> object based on this B<DH_METHOD>. Any +new B<DH> object will have those flags set by default. + +DH_meth_dup() creates a duplicate copy of the B<DH_METHOD> object passed as a +parameter. This might be useful for creating a new B<DH_METHOD> based on an +existing one, but with some differences. + +DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory +associated with it. + +DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This +is a pointer to the internal name string and so should not be freed by the +caller. DH_meth_set1_name() sets the name of the DH_METHOD to B<name>. The +string is duplicated and the copy is stored in the DH_METHOD structure, so the +caller remains responsible for freeing the memory associated with the name. + +DH_meth_get_flags() returns the current value of the flags associated with this +DH_METHOD. DH_meth_set_flags() provides the ability to set these flags. + +The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the +ability to associate implementation specific data with the DH_METHOD. It is +the application's responsibility to free this data before the DH_METHOD is +freed via a call to DH_meth_free(). + +DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the +function used for generating a new DH key pair respectively. This function will +be called in response to the application calling DH_generate_key(). The +parameter for the function has the same meaning as for DH_generate_key(). + +DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the +function used for computing a new DH shared secret respectively. This function +will be called in response to the application calling DH_compute_key(). The +parameters for the function have the same meaning as for DH_compute_key(). + +DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function +used for computing the following value: + + r = a ^ p mod m + +This function will be called by the default OpenSSL function for +DH_generate_key(). The result is stored in the B<r> parameter. This function +may be NULL unless using the default generate key function, in which case it +must be present. + +DH_meth_get_init() and DH_meth_set_init() get and set the function used +for creating a new DH instance respectively. This function will be +called in response to the application calling DH_new() (if the current default +DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method() +functions will allocate the memory for the new DH object, and a pointer to this +newly allocated structure will be passed as a parameter to the function. This +function may be NULL. + +DH_meth_get_finish() and DH_meth_set_finish() get and set the function used +for destroying an instance of a DH object respectively. This function will be +called in response to the application calling DH_free(). A pointer to the DH +to be destroyed is passed as a parameter. The destroy function should be used +for DH implementation specific clean up. The memory for the DH itself should +not be freed by this function. This function may be NULL. + +DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the +function used for generating DH parameters respectively. This function will be +called in response to the application calling DH_generate_parameters_ex() (or +DH_generate_parameters()). The parameters for the function have the same +meaning as for DH_generate_parameters_ex(). This function may be NULL. + +=head1 RETURN VALUES + +DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object +or NULL on failure. + +DH_meth_get0_name() and DH_meth_get_flags() return the name and flags +associated with the DH_METHOD respectively. + +All other DH_meth_get_*() functions return the appropriate function pointer +that has been set in the DH_METHOD, or NULL if no such pointer has yet been +set. + +DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or +0 on failure. + +=head1 SEE ALSO + +L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>, +L<DH_set_method(3)>, L<DH_size(3)>, L<DH_get0_pqg(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DH_new.pod b/openssl-1.1.0h/doc/crypto/DH_new.pod new file mode 100644 index 0000000..959a470 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DH_new.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +DH_new, DH_free - allocate and free DH objects + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + DH* DH_new(void); + + void DH_free(DH *dh); + +=head1 DESCRIPTION + +DH_new() allocates and initializes a B<DH> structure. + +DH_free() frees the B<DH> structure and its components. The values are +erased before the memory is returned to the system. +If B<dh> is NULL nothing is done. + +=head1 RETURN VALUES + +If the allocation fails, DH_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns +a pointer to the newly allocated structure. + +DH_free() returns no value. + +=head1 SEE ALSO + +L<dh(3)>, L<ERR_get_error(3)>, +L<DH_generate_parameters(3)>, +L<DH_generate_key(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DH_set_method.pod b/openssl-1.1.0h/doc/crypto/DH_set_method.pod new file mode 100644 index 0000000..2100608 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DH_set_method.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +DH_set_default_method, DH_get_default_method, +DH_set_method, DH_new_method, DH_OpenSSL - select DH method + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + void DH_set_default_method(const DH_METHOD *meth); + + const DH_METHOD *DH_get_default_method(void); + + int DH_set_method(DH *dh, const DH_METHOD *meth); + + DH *DH_new_method(ENGINE *engine); + + const DH_METHOD *DH_OpenSSL(void); + +=head1 DESCRIPTION + +A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman +operations. By modifying the method, alternative implementations +such as hardware accelerators may be used. IMPORTANT: See the NOTES section for +important information about how these DH API functions are affected by the use +of B<ENGINE> API calls. + +Initially, the default DH_METHOD is the OpenSSL internal implementation, as +returned by DH_OpenSSL(). + +DH_set_default_method() makes B<meth> the default method for all DH +structures created later. +B<NB>: This is true only whilst no ENGINE has been set +as a default for DH, so this function is no longer recommended. +This function is not thread-safe and should not be called at the same time +as other OpenSSL functions. + +DH_get_default_method() returns a pointer to the current default DH_METHOD. +However, the meaningfulness of this result is dependent on whether the ENGINE +API is being used, so this function is no longer recommended. + +DH_set_method() selects B<meth> to perform all operations using the key B<dh>. +This will replace the DH_METHOD used by the DH key and if the previous method +was supplied by an ENGINE, the handle to that ENGINE will be released during the +change. It is possible to have DH keys that only work with certain DH_METHOD +implementations (eg. from an ENGINE module that supports embedded +hardware-protected keys), and in such cases attempting to change the DH_METHOD +for the key can have unexpected results. + +DH_new_method() allocates and initializes a DH structure so that B<engine> will +be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH +operations is used, and if no default ENGINE is set, the DH_METHOD controlled by +DH_set_default_method() is used. + +A new DH_METHOD object may be constructed using DH_meth_new() (see +L<DH_meth_new(3)>). + +=head1 RETURN VALUES + +DH_OpenSSL() and DH_get_default_method() return pointers to the respective +B<DH_METHOD>s. + +DH_set_default_method() returns no value. + +DH_set_method() returns non-zero if the provided B<meth> was successfully set as +the method for B<dh> (including unloading the ENGINE handle if the previous +method was supplied by an ENGINE). + +DH_new_method() returns NULL and sets an error code that can be obtained by +L<ERR_get_error(3)> if the allocation fails. Otherwise it +returns a pointer to the newly allocated structure. + +=head1 SEE ALSO + +L<dh(3)>, L<DH_new(3)>, L<DH_meth_new(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DH_size.pod b/openssl-1.1.0h/doc/crypto/DH_size.pod new file mode 100644 index 0000000..8c1d151 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DH_size.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +DH_size, DH_bits - get Diffie-Hellman prime size + +=head1 SYNOPSIS + +#include <openssl/dh.h> + +int DH_size(const DH *dh); + +int DH_bits(const DH *dh); + +=head1 DESCRIPTION + +DH_size() returns the Diffie-Hellman prime size in bytes. It can be used +to determine how much memory must be allocated for the shared secret +computed by DH_compute_key(). + +DH_bits() returns the number of significant bits. + +B<dh> and B<dh-E<gt>p> must not be B<NULL>. + +=head1 RETURN VALUE + +The size. + +=head1 SEE ALSO + +L<dh(3)>, L<DH_generate_key(3)>, +L<BN_num_bits(3)> + +=head1 HISTORY + +DH_bits() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_SIG_new.pod b/openssl-1.1.0h/doc/crypto/DSA_SIG_new.pod new file mode 100644 index 0000000..7503460 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_SIG_new.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +DSA_SIG_get0, DSA_SIG_set0, +DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA_SIG *DSA_SIG_new(void); + void DSA_SIG_free(DSA_SIG *a); + void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps); + int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s); + +=head1 DESCRIPTION + +DSA_SIG_new() allocates an empty B<DSA_SIG> structure. + +DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The +values are erased before the memory is returned to the system. + +DSA_SIG_get0() returns internal pointers to the B<r> and B<s> values contained +in B<sig>. + +The B<r> and B<s> values can be set by calling DSA_SIG_set0() and passing the +new values for B<r> and B<s> as parameters to the function. Calling this +function transfers the memory management of the values to the DSA_SIG object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. + +=head1 RETURN VALUES + +If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an +error code that can be obtained by +L<ERR_get_error(3)>. Otherwise it returns a pointer +to the newly allocated structure. + +DSA_SIG_free() returns no value. + +DSA_SIG_set0() returns 1 on success or 0 on failure. + +=head1 SEE ALSO + +L<dsa(3)>, L<ERR_get_error(3)>, +L<DSA_do_sign(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_do_sign.pod b/openssl-1.1.0h/doc/crypto/DSA_do_sign.pod new file mode 100644 index 0000000..5e56d20 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_do_sign.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +DSA_do_sign, DSA_do_verify - raw DSA signature operations + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); + + int DSA_do_verify(const unsigned char *dgst, int dgst_len, + DSA_SIG *sig, DSA *dsa); + +=head1 DESCRIPTION + +DSA_do_sign() computes a digital signature on the B<len> byte message +digest B<dgst> using the private key B<dsa> and returns it in a +newly allocated B<DSA_SIG> structure. + +L<DSA_sign_setup(3)> may be used to precompute part +of the signing operation in case signature generation is +time-critical. + +DSA_do_verify() verifies that the signature B<sig> matches a given +message digest B<dgst> of size B<len>. B<dsa> is the signer's public +key. + +=head1 RETURN VALUES + +DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() +returns 1 for a valid signature, 0 for an incorrect signature and -1 +on error. The error codes can be obtained by +L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, +L<DSA_SIG_new(3)>, +L<DSA_sign(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_dup_DH.pod b/openssl-1.1.0h/doc/crypto/DSA_dup_DH.pod new file mode 100644 index 0000000..6967ef3 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_dup_DH.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +DSA_dup_DH - create a DH structure out of DSA structure + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DH * DSA_dup_DH(const DSA *r); + +=head1 DESCRIPTION + +DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q +is lost during that conversion, but the resulting DH parameters +contain its length. + +=head1 RETURN VALUE + +DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The +error codes can be obtained by L<ERR_get_error(3)>. + +=head1 NOTE + +Be careful to avoid small subgroup attacks when using this. + +=head1 SEE ALSO + +L<dh(3)>, L<dsa(3)>, L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_generate_key.pod b/openssl-1.1.0h/doc/crypto/DSA_generate_key.pod new file mode 100644 index 0000000..4781abe --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_generate_key.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +DSA_generate_key - generate DSA key pair + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + int DSA_generate_key(DSA *a); + +=head1 DESCRIPTION + +DSA_generate_key() expects B<a> to contain DSA parameters. It generates +a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>. + +The PRNG must be seeded prior to calling DSA_generate_key(). + +=head1 RETURN VALUE + +DSA_generate_key() returns 1 on success, 0 otherwise. +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, +L<DSA_generate_parameters(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_generate_parameters.pod b/openssl-1.1.0h/doc/crypto/DSA_generate_parameters.pod new file mode 100644 index 0000000..fc05149 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_generate_parameters.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + int DSA_generate_parameters_ex(DSA *dsa, int bits, + const unsigned char *seed, int seed_len, + int *counter_ret, unsigned long *h_ret, BN_GENCB *cb); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x00908000L + DSA *DSA_generate_parameters(int bits, unsigned char *seed, + int seed_len, int *counter_ret, unsigned long *h_ret, + void (*callback)(int, int, void *), void *cb_arg); + #endif + +=head1 DESCRIPTION + +DSA_generate_parameters_ex() generates primes p and q and a generator g +for use in the DSA and stores the result in B<dsa>. + +B<bits> is the length of the prime p to be generated. +For lengths under 2048 bits, the length of q is 160 bits; for lengths +greater than or equal to 2048 bits, the length of q is set to 256 bits. + +If B<seed> is NULL, the primes will be generated at random. +If B<seed_len> is less than the length of q, an error is returned. + +DSA_generate_parameters_ex() places the iteration count in +*B<counter_ret> and a counter used for finding a generator in +*B<h_ret>, unless these are B<NULL>. + +A callback function may be used to provide feedback about the progress +of the key generation. If B<cb> is not B<NULL>, it will be +called as shown below. For information on the BN_GENCB structure and the +BN_GENCB_call function discussed below, refer to +L<BN_generate_prime(3)>. + +=over 2 + +=item * + +When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called +(m is 0 for the first candidate). + +=item * + +When a candidate for q has passed a test by trial division, +B<BN_GENCB_call(cb, 1, -1)> is called. +While a candidate for q is tested by Miller-Rabin primality tests, +B<BN_GENCB_call(cb, 1, i)> is called in the outer loop +(once for each witness that confirms that the candidate may be prime); +i is the loop counter (starting at 0). + +=item * + +When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and +B<BN_GENCB_call(cb, 3, 0)> are called. + +=item * + +Before a candidate for p (other than the first) is generated and tested, +B<BN_GENCB_call(cb, 0, counter)> is called. + +=item * + +When a candidate for p has passed the test by trial division, +B<BN_GENCB_call(cb, 1, -1)> is called. +While it is tested by the Miller-Rabin primality test, +B<BN_GENCB_call(cb, 1, i)> is called in the outer loop +(once for each witness that confirms that the candidate may be prime). +i is the loop counter (starting at 0). + +=item * + +When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called. + +=item * + +When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called. + +=back + +DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and +instead a newly allocated B<DSA> structure is returned. Additionally "old +style" callbacks are used instead of the newer BN_GENCB based approach. +Refer to L<BN_generate_prime(3)> for further information. + +=head1 RETURN VALUE + +DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise. + +DSA_generate_parameters() returns a pointer to the DSA structure, or +B<NULL> if the parameter generation fails. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 BUGS + +Seed lengths E<gt> 20 are not supported. + +=head1 SEE ALSO + +L<DSA_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, +L<DSA_free(3)>, L<BN_generate_prime(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_get0_pqg.pod b/openssl-1.1.0h/doc/crypto/DSA_get0_pqg.pod new file mode 100644 index 0000000..6c1c09a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_get0_pqg.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +DSA_get0_pqg, DSA_set0_pqg, DSA_get0_key, DSA_set0_key, DSA_clear_flags, +DSA_test_flags, DSA_set_flags, DSA_get0_engine - Routines for getting and +setting data in a DSA object + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + void DSA_get0_pqg(const DSA *d, + const BIGNUM **p, const BIGNUM **q, const BIGNUM **g); + int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g); + void DSA_get0_key(const DSA *d, + const BIGNUM **pub_key, const BIGNUM **priv_key); + int DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key); + void DSA_clear_flags(DSA *d, int flags); + int DSA_test_flags(const DSA *d, int flags); + void DSA_set_flags(DSA *d, int flags); + ENGINE *DSA_get0_engine(DSA *d); + +=head1 DESCRIPTION + +A DSA object contains the parameters B<p>, B<q> and B<g>. It also contains a +public key (B<pub_key>) and (optionally) a private key (B<priv_key>). + +The B<p>, B<q> and B<g> parameters can be obtained by calling DSA_get0_pqg(). +If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set +to NULL. Otherwise they are set to pointers to their respective values. These +point directly to the internal representations of the values and therefore +should not be freed directly. + +The B<p>, B<q> and B<g> values can be set by calling DSA_set0_pqg() and passing +the new values for B<p>, B<q> and B<g> as parameters to the function. Calling +this function transfers the memory management of the values to the DSA object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. + +To get the public and private key values use the DSA_get0_key() function. A +pointer to the public key will be stored in B<*pub_key>, and a pointer to the +private key will be stored in B<*priv_key>. Either may be NULL if they have not +been set yet, although if the private key has been set then the public key must +be. The values point to the internal representation of the public key and +private key values. This memory should not be freed directly. + +The public and private key values can be set using DSA_set0_key(). The public +key must be non-NULL the first time this function is called on a given DSA +object. The private key may be NULL. On subsequent calls, either may be NULL, +which means the corresponding DSA field is left untouched. As for DSA_set0_pqg() +this function transfers the memory management of the key values to the DSA +object, and therefore they should not be freed directly after this function has +been called. + +DSA_set_flags() sets the flags in the B<flags> parameter on the DSA object. +Multiple flags can be passed in one go (bitwise ORed together). Any flags that +are already set are left set. DSA_test_flags() tests to see whether the flags +passed in the B<flags> parameter are currently set in the DSA object. Multiple +flags can be tested in one go. All flags that are currently set are returned, or +zero if none of the flags are set. DSA_clear_flags() clears the specified flags +within the DSA object. + +DSA_get0_engine() returns a handle to the ENGINE that has been set for this DSA +object, or NULL if no such ENGINE has been set. + +=head1 NOTES + +Values retrieved with DSA_get0_key() are owned by the DSA object used +in the call and may therefore I<not> be passed to DSA_set0_key(). If +needed, duplicate the received value using BN_dup() and pass the +duplicate. The same applies to DSA_get0_pqg() and DSA_set0_pqg(). + +=head1 RETURN VALUES + +DSA_set0_pqg() and DSA_set0_key() return 1 on success or 0 on failure. + +DSA_test_flags() returns the current state of the flags in the DSA object. + +DSA_get0_engine() returns the ENGINE set for the DSA object or NULL if no ENGINE +has been set. + +=head1 SEE ALSO + +L<dsa(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>, +L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>, +L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_meth_new(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_meth_new.pod b/openssl-1.1.0h/doc/crypto/DSA_meth_new.pod new file mode 100644 index 0000000..948ab29 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_meth_new.pod @@ -0,0 +1,193 @@ +=pod + +=head1 NAME + +DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get0_name, +DSA_meth_set1_name, DSA_meth_get_flags, DSA_meth_set_flags, +DSA_meth_get0_app_data, DSA_meth_set0_app_data, DSA_meth_get_sign, +DSA_meth_set_sign, DSA_meth_get_sign_setup, DSA_meth_set_sign_setup, +DSA_meth_get_verify, DSA_meth_set_verify, DSA_meth_get_mod_exp, +DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp, +DSA_meth_get_init, DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish, +DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen, +DSA_meth_set_keygen - Routines to build up DSA methods + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA_METHOD *DSA_meth_new(const char *name, int flags); + void DSA_meth_free(DSA_METHOD *dsam); + DSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth); + const char *DSA_meth_get0_name(const DSA_METHOD *dsam); + int DSA_meth_set1_name(DSA_METHOD *dsam, const char *name); + int DSA_meth_get_flags(DSA_METHOD *dsam); + int DSA_meth_set_flags(DSA_METHOD *dsam, int flags); + void *DSA_meth_get0_app_data(const DSA_METHOD *dsam); + int DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data); + DSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam)) + (const unsigned char *, int, DSA *); + int DSA_meth_set_sign(DSA_METHOD *dsam, + DSA_SIG *(*sign) (const unsigned char *, int, DSA *)); + int (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam)) + (DSA *, BN_CTX *, BIGNUM **, BIGNUM **); + int DSA_meth_set_sign_setup(DSA_METHOD *dsam, + int (*sign_setup) (DSA *, BN_CTX *, BIGNUM **, BIGNUM **)); + int (*DSA_meth_get_verify(const DSA_METHOD *dsam)) + (const unsigned char *, int , DSA_SIG *, DSA *); + int DSA_meth_set_verify(DSA_METHOD *dsam, + int (*verify) (const unsigned char *, int, DSA_SIG *, DSA *)); + int (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam)) + (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2, BIGNUM *p2, + BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont); + int DSA_meth_set_mod_exp(DSA_METHOD *dsam, + int (*mod_exp) (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2, + BIGNUM *p2, BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont)); + int (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam)) + (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m, + BN_CTX *ctx, BN_MONT_CTX *mont); + int DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam, + int (*bn_mod_exp) (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont)); + int (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *); + int DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *)); + int (*DSA_meth_get_finish(const DSA_METHOD *dsam)) (DSA *); + int DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish) (DSA *)); + int (*DSA_meth_get_paramgen(const DSA_METHOD *dsam)) + (DSA *, int, const unsigned char *, int, int *, unsigned long *, + BN_GENCB *); + int DSA_meth_set_paramgen(DSA_METHOD *dsam, + int (*paramgen) (DSA *, int, const unsigned char *, int, int *, + unsigned long *, BN_GENCB *)); + int (*DSA_meth_get_keygen(const DSA_METHOD *dsam)) (DSA *); + int DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen) (DSA *)); + +=head1 DESCRIPTION + +The B<DSA_METHOD> type is a structure used for the provision of custom DSA +implementations. It provides a set of of functions used by OpenSSL for the +implementation of the various DSA capabilities. See the L<dsa> page for more +information. + +DSA_meth_new() creates a new B<DSA_METHOD> structure. It should be given a +unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated +string, which will be duplicated and stored in the B<DSA_METHOD> object. It is +the callers responsibility to free the original string. The flags will be used +during the construction of a new B<DSA> object based on this B<DSA_METHOD>. Any +new B<DSA> object will have those flags set by default. + +DSA_meth_dup() creates a duplicate copy of the B<DSA_METHOD> object passed as a +parameter. This might be useful for creating a new B<DSA_METHOD> based on an +existing one, but with some differences. + +DSA_meth_free() destroys a B<DSA_METHOD> structure and frees up any memory +associated with it. + +DSA_meth_get0_name() will return a pointer to the name of this DSA_METHOD. This +is a pointer to the internal name string and so should not be freed by the +caller. DSA_meth_set1_name() sets the name of the DSA_METHOD to B<name>. The +string is duplicated and the copy is stored in the DSA_METHOD structure, so the +caller remains responsible for freeing the memory associated with the name. + +DSA_meth_get_flags() returns the current value of the flags associated with this +DSA_METHOD. DSA_meth_set_flags() provides the ability to set these flags. + +The functions DSA_meth_get0_app_data() and DSA_meth_set0_app_data() provide the +ability to associate implementation specific data with the DSA_METHOD. It is +the application's responsibility to free this data before the DSA_METHOD is +freed via a call to DSA_meth_free(). + +DSA_meth_get_sign() and DSA_meth_set_sign() get and set the function used for +creating a DSA signature respectively. This function will be +called in response to the application calling DSA_do_sign() (or DSA_sign()). The +parameters for the function have the same meaning as for DSA_do_sign(). + +DSA_meth_get_sign_setup() and DSA_meth_set_sign_setup() get and set the function +used for precalculating the DSA signature values B<k^-1> and B<r>. This function +will be called in response to the application calling DSA_sign_setup(). The +parameters for the function have the same meaning as for DSA_sign_setup(). + +DSA_meth_get_verify() and DSA_meth_set_verify() get and set the function used +for verifying a DSA signature respectively. This function will be called in +response to the application calling DSA_do_verify() (or DSA_verify()). The +parameters for the function have the same meaning as for DSA_do_verify(). + +DSA_meth_get_mod_exp() and DSA_meth_set_mod_exp() get and set the function used +for computing the following value: + + rr = a1^p1 * a2^p2 mod m + +This function will be called by the default OpenSSL method during verification +of a DSA signature. The result is stored in the B<rr> parameter. This function +may be NULL. + +DSA_meth_get_bn_mod_exp() and DSA_meth_set_bn_mod_exp() get and set the function +used for computing the following value: + + r = a ^ p mod m + +This function will be called by the default OpenSSL function for +DSA_sign_setup(). The result is stored in the B<r> parameter. This function +may be NULL. + +DSA_meth_get_init() and DSA_meth_set_init() get and set the function used +for creating a new DSA instance respectively. This function will be +called in response to the application calling DSA_new() (if the current default +DSA_METHOD is this one) or DSA_new_method(). The DSA_new() and DSA_new_method() +functions will allocate the memory for the new DSA object, and a pointer to this +newly allocated structure will be passed as a parameter to the function. This +function may be NULL. + +DSA_meth_get_finish() and DSA_meth_set_finish() get and set the function used +for destroying an instance of a DSA object respectively. This function will be +called in response to the application calling DSA_free(). A pointer to the DSA +to be destroyed is passed as a parameter. The destroy function should be used +for DSA implementation specific clean up. The memory for the DSA itself should +not be freed by this function. This function may be NULL. + +DSA_meth_get_paramgen() and DSA_meth_set_paramgen() get and set the function +used for generating DSA parameters respectively. This function will be called in +response to the application calling DSA_generate_parameters_ex() (or +DSA_generate_parameters()). The parameters for the function have the same +meaning as for DSA_generate_parameters_ex(). + +DSA_meth_get_keygen() and DSA_meth_set_keygen() get and set the function +used for generating a new DSA key pair respectively. This function will be +called in response to the application calling DSA_generate_key(). The parameter +for the function has the same meaning as for DSA_generate_key(). + +=head1 RETURN VALUES + +DSA_meth_new() and DSA_meth_dup() return the newly allocated DSA_METHOD object +or NULL on failure. + +DSA_meth_get0_name() and DSA_meth_get_flags() return the name and flags +associated with the DSA_METHOD respectively. + +All other DSA_meth_get_*() functions return the appropriate function pointer +that has been set in the DSA_METHOD, or NULL if no such pointer has yet been +set. + +DSA_meth_set1_name() and all DSA_meth_set_*() functions return 1 on success or +0 on failure. + +=head1 SEE ALSO + +L<dsa(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>, +L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>, +L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_get0_pqg(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_new.pod b/openssl-1.1.0h/doc/crypto/DSA_new.pod new file mode 100644 index 0000000..a967ab5 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_new.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +DSA_new, DSA_free - allocate and free DSA objects + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA* DSA_new(void); + + void DSA_free(DSA *dsa); + +=head1 DESCRIPTION + +DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to +calling DSA_new_method(NULL). + +DSA_free() frees the B<DSA> structure and its components. The values are +erased before the memory is returned to the system. +If B<dsa> is NULL nothing is done. + +=head1 RETURN VALUES + +If the allocation fails, DSA_new() returns B<NULL> and sets an error +code that can be obtained by +L<ERR_get_error(3)>. Otherwise it returns a pointer +to the newly allocated structure. + +DSA_free() returns no value. + +=head1 SEE ALSO + +L<dsa(3)>, L<ERR_get_error(3)>, +L<DSA_generate_parameters(3)>, +L<DSA_generate_key(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_set_method.pod b/openssl-1.1.0h/doc/crypto/DSA_set_method.pod new file mode 100644 index 0000000..d870f56 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_set_method.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +DSA_set_default_method, DSA_get_default_method, +DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + void DSA_set_default_method(const DSA_METHOD *meth); + + const DSA_METHOD *DSA_get_default_method(void); + + int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); + + DSA *DSA_new_method(ENGINE *engine); + + DSA_METHOD *DSA_OpenSSL(void); + +=head1 DESCRIPTION + +A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA +operations. By modifying the method, alternative implementations +such as hardware accelerators may be used. IMPORTANT: See the NOTES section for +important information about how these DSA API functions are affected by the use +of B<ENGINE> API calls. + +Initially, the default DSA_METHOD is the OpenSSL internal implementation, +as returned by DSA_OpenSSL(). + +DSA_set_default_method() makes B<meth> the default method for all DSA +structures created later. +B<NB>: This is true only whilst no ENGINE has +been set as a default for DSA, so this function is no longer recommended. +This function is not thread-safe and should not be called at the same time +as other OpenSSL functions. + +DSA_get_default_method() returns a pointer to the current default +DSA_METHOD. However, the meaningfulness of this result is dependent on +whether the ENGINE API is being used, so this function is no longer +recommended. + +DSA_set_method() selects B<meth> to perform all operations using the key +B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the +previous method was supplied by an ENGINE, the handle to that ENGINE will +be released during the change. It is possible to have DSA keys that only +work with certain DSA_METHOD implementations (eg. from an ENGINE module +that supports embedded hardware-protected keys), and in such cases +attempting to change the DSA_METHOD for the key can have unexpected +results. See L<DSA_meth_new> for information on constructing custom DSA_METHOD +objects; + +DSA_new_method() allocates and initializes a DSA structure so that B<engine> +will be used for the DSA operations. If B<engine> is NULL, the default engine +for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD +controlled by DSA_set_default_method() is used. + +=head1 RETURN VALUES + +DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective +B<DSA_METHOD>s. + +DSA_set_default_method() returns no value. + +DSA_set_method() returns non-zero if the provided B<meth> was successfully set as +the method for B<dsa> (including unloading the ENGINE handle if the previous +method was supplied by an ENGINE). + +DSA_new_method() returns NULL and sets an error code that can be +obtained by L<ERR_get_error(3)> if the allocation +fails. Otherwise it returns a pointer to the newly allocated structure. + +=head1 SEE ALSO + +L<dsa(3)>, L<DSA_new(3)>, L<DSA_meth_new(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_sign.pod b/openssl-1.1.0h/doc/crypto/DSA_sign.pod new file mode 100644 index 0000000..ba0f6b8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_sign.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + int DSA_sign(int type, const unsigned char *dgst, int len, + unsigned char *sigret, unsigned int *siglen, DSA *dsa); + + int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, + BIGNUM **rp); + + int DSA_verify(int type, const unsigned char *dgst, int len, + unsigned char *sigbuf, int siglen, DSA *dsa); + +=head1 DESCRIPTION + +DSA_sign() computes a digital signature on the B<len> byte message +digest B<dgst> using the private key B<dsa> and places its ASN.1 DER +encoding at B<sigret>. The length of the signature is places in +*B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory. + +DSA_sign_setup() may be used to precompute part of the signing +operation in case signature generation is time-critical. It expects +B<dsa> to contain DSA parameters. It places the precomputed values +in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing +the old ones unless *B<kinvp> and *B<rp> are NULL. These values may +be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>. +B<ctx> is a pre-allocated B<BN_CTX> or NULL. + +DSA_verify() verifies that the signature B<sigbuf> of size B<siglen> +matches a given message digest B<dgst> of size B<len>. +B<dsa> is the signer's public key. + +The B<type> parameter is ignored. + +The PRNG must be seeded before DSA_sign() (or DSA_sign_setup()) +is called. + +=head1 RETURN VALUES + +DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. +DSA_verify() returns 1 for a valid signature, 0 for an incorrect +signature and -1 on error. The error codes can be obtained by +L<ERR_get_error(3)>. + +=head1 CONFORMING TO + +US Federal Information Processing Standard FIPS 186 (Digital Signature +Standard, DSS), ANSI X9.30 + +=head1 SEE ALSO + +L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, +L<DSA_do_sign(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/DSA_size.pod b/openssl-1.1.0h/doc/crypto/DSA_size.pod new file mode 100644 index 0000000..16e6f3a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/DSA_size.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +DSA_size, DSA_bits - get DSA signature size or key bits + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + int DSA_size(const DSA *dsa); + int DSA_bits(const DSA *dsa); + +=head1 DESCRIPTION + +DSA_size() returns the maximum size of an ASN.1 encoded DSA signature +for key B<dsa> in bytes. It can be used to determine how much memory must +be allocated for a DSA signature. + +B<dsa-E<gt>q> must not be B<NULL>. + +DSA_bits() returns the number of bits in key B<dsa>: this is the number +of bits in the B<p> parameter. + +=head1 RETURN VALUE + +DSA_size() returns the size in bytes. + +DSA_bits() returns the number of bits in the key. + +=head1 SEE ALSO + +L<dsa(3)>, L<DSA_sign(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ECDSA_SIG_new.pod b/openssl-1.1.0h/doc/crypto/ECDSA_SIG_new.pod new file mode 100644 index 0000000..9e1f662 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ECDSA_SIG_new.pod @@ -0,0 +1,207 @@ +=pod + +=head1 NAME + +ECDSA_SIG_get0, ECDSA_SIG_set0, +ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, +ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, +ECDSA_sign_ex, ECDSA_do_sign_ex - low level elliptic curve digital signature +algorithm (ECDSA) functions + +=head1 SYNOPSIS + + #include <openssl/ecdsa.h> + + ECDSA_SIG *ECDSA_SIG_new(void); + void ECDSA_SIG_free(ECDSA_SIG *sig); + void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps); + int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s); + int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); + ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len); + int ECDSA_size(const EC_KEY *eckey); + + int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen, + unsigned char *sig, unsigned int *siglen, EC_KEY *eckey); + ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len, + EC_KEY *eckey); + + int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen, + const unsigned char *sig, int siglen, EC_KEY *eckey); + int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, + const ECDSA_SIG *sig, EC_KEY* eckey); + + ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, + const BIGNUM *kinv, const BIGNUM *rp, + EC_KEY *eckey); + int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp); + int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen, + unsigned char *sig, unsigned int *siglen, + const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey); + +=head1 DESCRIPTION + +Note: these functions provide a low level interface to ECDSA. Most +applications should use the higher level B<EVP> interface such as +L<EVP_DigestSignInit(3)> or L<EVP_DigestVerifyInit(3)> instead. + +B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the +B<r> and B<s> value of an ECDSA signature (see X9.62 or FIPS 186-2). + +ECDSA_SIG_new() allocates an empty B<ECDSA_SIG> structure. Note: before +OpenSSL 1.1.0 the: the B<r> and B<s> components were initialised. + +ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>. + +ECDSA_SIG_get0() returns internal pointers the B<r> and B<s> values contained +in B<sig>. + +The B<r> and B<s> values can be set by calling ECDSA_SIG_set0() and passing the +new values for B<r> and B<s> as parameters to the function. Calling this +function transfers the memory management of the values to the ECDSA_SIG object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. + +i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature B<sig> and +writes the encoded signature to B<*pp> (note: if B<pp> is NULL i2d_ECDSA_SIG() +returns the expected length in bytes of the DER encoded signature). +i2d_ECDSA_SIG() returns the length of the DER encoded signature (or 0 on +error). + +d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns the decoded +signature in a newly allocated B<ECDSA_SIG> structure. B<*sig> points to the +buffer containing the DER encoded signature of size B<len>. + +ECDSA_size() returns the maximum length of a DER encoded ECDSA signature +created with the private EC key B<eckey>. + +ECDSA_sign() computes a digital signature of the B<dgstlen> bytes hash value +B<dgst> using the private EC key B<eckey>. The DER encoded signatures is +stored in B<sig> and its length is returned in B<sig_len>. Note: B<sig> must +point to ECDSA_size(eckey) bytes of memory. The parameter B<type> is currently +ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with B<kinv> +and B<rp> set to NULL. + +ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned +as a newly allocated B<ECDSA_SIG> structure (or NULL on error). ECDSA_do_sign() +is a wrapper function for ECDSA_do_sign_ex() with B<kinv> and B<rp> set to +NULL. + +ECDSA_verify() verifies that the signature in B<sig> of size B<siglen> is a +valid ECDSA signature of the hash value B<dgst> of size B<dgstlen> using the +public key B<eckey>. The parameter B<type> is ignored. + +ECDSA_do_verify() is similar to ECDSA_verify() except the signature is +presented in the form of a pointer to an B<ECDSA_SIG> structure. + +The remaining functions utilise the internal B<kinv> and B<r> values used +during signature computation. Most applications will never need to call these +and some external ECDSA ENGINE implementations may not support them at all if +either B<kinv> or B<r> is not B<NULL>. + +ECDSA_sign_setup() may be used to precompute parts of the signing operation. +B<eckey> is the private EC key and B<ctx> is a pointer to B<BN_CTX> structure +(or NULL). The precomputed values or returned in B<kinv> and B<rp> and can be +used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex(). + +ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes hash value +B<dgst> using the private EC key B<eckey> and the optional pre-computed values +B<kinv> and B<rp>. The DER encoded signature is stored in B<sig> and its +length is returned in B<sig_len>. Note: B<sig> must point to ECDSA_size(eckey) +bytes of memory. The parameter B<type> is ignored. + +ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is +returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error). + +=head1 RETURN VALUES + +ECDSA_SIG_set0() returns 1 on success or 0 on failure. + +ECDSA_size() returns the maximum length signature or 0 on error. + +ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful +or 0 on error. + +ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated +B<ECDSA_SIG> structure or NULL on error. + +ECDSA_verify() and ECDSA_do_verify() return 1 for a valid +signature, 0 for an invalid signature and -1 on error. +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 EXAMPLES + +Creating an ECDSA signature of a given SHA-256 hash value using the +named curve prime256v1 (aka P-256). + +First step: create an EC_KEY object (note: this part is B<not> ECDSA +specific) + + int ret; + ECDSA_SIG *sig; + EC_KEY *eckey; + eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1); + if (eckey == NULL) { + /* error */ + } + if (EC_KEY_generate_key(eckey) == 0) { + /* error */ + } + +Second step: compute the ECDSA signature of a SHA-256 hash value +using ECDSA_do_sign(): + + sig = ECDSA_do_sign(digest, 32, eckey); + if (sig == NULL) { + /* error */ + } + +or using ECDSA_sign(): + + unsigned char *buffer, *pp; + int buf_len; + buf_len = ECDSA_size(eckey); + buffer = OPENSSL_malloc(buf_len); + pp = buffer; + if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) { + /* error */ + } + +Third step: verify the created ECDSA signature using ECDSA_do_verify(): + + ret = ECDSA_do_verify(digest, 32, sig, eckey); + +or using ECDSA_verify(): + + ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey); + +and finally evaluate the return value: + + if (ret == 1) { + /* signature ok */ + } else if (ret == 0) { + /* incorrect signature */ + } else { + /* error */ + } + +=head1 CONFORMING TO + +ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 +(Digital Signature Standard, DSS) + +=head1 SEE ALSO + +L<DSA_new(3)>, +L<EVP_DigestSignInit(3)>, +L<EVP_DigestVerifyInit(3)> + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ECPKParameters_print.pod b/openssl-1.1.0h/doc/crypto/ECPKParameters_print.pod new file mode 100644 index 0000000..24b6bb9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ECPKParameters_print.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and +encoding ASN1 representations of elliptic curve entities + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); + int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); + +=head1 DESCRIPTION + +The ECPKParameters represent the public parameters for an +B<EC_GROUP> structure, which represents a curve. + +The ECPKParameters_print() and ECPKParameters_print_fp() functions print +a human-readable output of the public parameters of the EC_GROUP to B<bp> +or B<fp>. The output lines are indented by B<off> spaces. + +=head1 RETURN VALUES + +ECPKParameters_print() and ECPKParameters_print_fp() +return 1 for success and 0 if an error occurs. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EC_GFp_simple_method.pod b/openssl-1.1.0h/doc/crypto/EC_GFp_simple_method.pod new file mode 100644 index 0000000..f283d8e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EC_GFp_simple_method.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining EC_METHOD objects + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + const EC_METHOD *EC_GFp_simple_method(void); + const EC_METHOD *EC_GFp_mont_method(void); + const EC_METHOD *EC_GFp_nist_method(void); + const EC_METHOD *EC_GFp_nistp224_method(void); + const EC_METHOD *EC_GFp_nistp256_method(void); + const EC_METHOD *EC_GFp_nistp521_method(void); + + const EC_METHOD *EC_GF2m_simple_method(void); + + int EC_METHOD_get_field_type(const EC_METHOD *meth); + +=head1 DESCRIPTION + +The Elliptic Curve library provides a number of different implementations through a single common interface. +When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)>) an +implementation method must be provided. The functions described here all return a const pointer to an +B<EC_METHOD> structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation +type for the form of curve selected is used. + +For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method. + +For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All +other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the +use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)>). EC_GFp_nist_method +offers an implementation optimised for use with NIST recommended curves (NIST curves are available through +EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)>). + +The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit +optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these +implementations are not available on all platforms. + +EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either +F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is +F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the +obj_mac.h header file. + +=head1 RETURN VALUES + +All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure. + +EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<d2i_ECPKParameters(3)>, +L<BN_mod_mul_montgomery(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EC_GROUP_copy.pod b/openssl-1.1.0h/doc/crypto/EC_GROUP_copy.pod new file mode 100644 index 0000000..fd5f58c --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EC_GROUP_copy.pod @@ -0,0 +1,206 @@ +=pod + +=head1 NAME + +EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor, +EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, +EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, +EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, +EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, +EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, +EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, +EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, +EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, +EC_GROUP_get_pentanomial_basis +- Functions for manipulating EC_GROUP objects + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); + EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); + + const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); + + int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); + const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); + + int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); + const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group); + int EC_GROUP_order_bits(const EC_GROUP *group); + int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); + const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group); + + void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); + int EC_GROUP_get_curve_name(const EC_GROUP *group); + + void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); + int EC_GROUP_get_asn1_flag(const EC_GROUP *group); + + void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); + point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); + + unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); + size_t EC_GROUP_get_seed_len(const EC_GROUP *); + size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); + + int EC_GROUP_get_degree(const EC_GROUP *group); + + int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); + + int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); + + int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); + + int EC_GROUP_get_basis_type(const EC_GROUP *); + int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); + int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, + unsigned int *k2, unsigned int *k3); + +=head1 DESCRIPTION + +EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD. + +EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created +EC_GROUP object. + +EC_GROUP_method_of obtains the EC_METHOD of B<group>. + +EC_GROUP_set_generator sets curve parameters that must be agreed by all participants using the curve. These +parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the +curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and +n-1 where n is the B<order>. The B<order> multiplied by the B<cofactor> gives the number of points on the curve. + +EC_GROUP_get0_generator returns the generator for the identified B<group>. + +The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters +with the respective order and cofactors for the B<group>. + +The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively +(see L<EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name +will return 0. + +The asn1_flag value is used to determine whether the curve encoding uses +explicit parameters or a named curve using an ASN1 OID: many applications only +support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the +named curve form is used and the parameters must have a corresponding +named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> the +parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag and +EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. +Note: B<OPENSSL_EC_EXPLICIT_CURVE> was first added to OpenSSL 1.1.0, for +previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL +1.1.0 the default form was to use explicit parameters (meaning that +applications would have to explicitly set the named curve form) in OpenSSL +1.1.0 and later the named curve form is the default. + +The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). +point_conversion_form_t is an enum defined as follows: + + typedef enum { + /** the point is encoded as z||x, where the octet z specifies + * which solution of the quadratic equation y is */ + POINT_CONVERSION_COMPRESSED = 2, + /** the point is encoded as z||x||y, where z is the octet 0x04 */ + POINT_CONVERSION_UNCOMPRESSED = 4, + /** the point is encoded as z||x||y, where the octet z specifies + * which solution of the quadratic equation y is */ + POINT_CONVERSION_HYBRID = 6 + } point_conversion_form_t; + +For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by +the octets for x, followed by the octets for y. + +For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For +POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of +the two possible solutions for y has been used, followed by the octets for x. + +For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two +possible solutions for y has been used, followed by the octets for x, followed by the octets for y. + +The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form +for the curve respectively. + +ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages +in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it. +If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library +does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block +containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the +builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using +EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use +this seed value, although it will be preserved in any ASN1 based communications. + +EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be +the value m. + +The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid. +For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is +simply b. In either case for the curve to be valid the discriminant must be non zero. + +The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include +verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has +the correct order. + +EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not. + +The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves +defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial +function f(x). This function is either a trinomial of the form: + +f(x) = x^m + x^k + 1 with m > k >= 1 + +or a pentanomial of the form: + +f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 + +The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The +function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly +the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>, +B<k2> and B<k3> respectively. + +=head1 RETURN VALUES + +The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check, +EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis. + +EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error. + +EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error. + +EC_GROUP_get0_generator returns the generator for the given curve or NULL on error. + +EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form +and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the +specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0. + +EC_GROUP_get0_order() returns an internal pointer to the group order. +EC_GROUP_get_order_bits() returns the number of bits in the group order. +EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor. + +EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not +specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified. + +EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is +0, the return value will be 1. On error 0 is returned. + +EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error. + +EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a +trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, +L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod b/openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod new file mode 100644 index 0000000..2f658dc --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EC_GROUP_new.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + +EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, +EC_GROUP_new, EC_GROUP_new_from_ecparameters, +EC_GROUP_new_from_ecpkparameters, +EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, +EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, +EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, +EC_get_builtin_curves - Functions for creating and destroying EC_GROUP +objects + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); + EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params) + EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params) + void EC_GROUP_free(EC_GROUP *group); + void EC_GROUP_clear_free(EC_GROUP *group); + + EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); + EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); + EC_GROUP *EC_GROUP_new_by_curve_name(int nid); + + int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); + int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); + int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + + ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params) + ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params) + + size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); + +=head1 DESCRIPTION + +Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the +prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised +elliptic curve equation as follows: + +y^2 mod p = x^3 +ax + b mod p + +The second form is those defined over a binary field F2^m where the elements of the field are integers of length at +most m bits. For this form the elliptic curve equation is modified to: + +y^2 + xy = x^3 + ax^2 + b (where b != 0) + +Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL +use a trinomial or a pentanomial for this parameter. + +A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see +L<EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or +EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively. +EC_GROUP_new_from_ecparameters() will create a group from the +specified B<params> and +EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>. + +EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>. +EC_group_get_curve_GFp obtains the previously set curve parameters. + +EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents +the irreducible polynomial - each bit represents a term in the polynomial. Therefore there will either be three +or five bits set dependent on whether the polynomial is a trinomial or a pentanomial. +EC_group_get_curve_GF2m obtains the previously set curve parameters. + +The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the +appropriate EC_group_set_curve function. An appropriate default implementation method will be used. + +Whilst the library can be used to create any curve using the functions described above, there are also a number of +predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function +EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function +will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of +curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be +provided. The return value is the total number of curves available (whether that number has been populated in B<r> or +not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available. +The EC_builtin_curve structure is defined as follows: + + typedef struct { + int nid; + const char *comment; + } EC_builtin_curve; + +Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve. + +In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to +be constructed. + +EC_GROUP_free frees the memory associated with the EC_GROUP. +If B<group> is NULL nothing is done. + +EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. +If B<group> is NULL nothing is done. + +=head1 RETURN VALUES + +All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error. + +EC_get_builtin_curves returns the number of builtin curves that are available. + +EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EC_KEY_get_enc_flags.pod b/openssl-1.1.0h/doc/crypto/EC_KEY_get_enc_flags.pod new file mode 100644 index 0000000..4f73a1d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EC_KEY_get_enc_flags.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +EC_KEY_get_enc_flags, EC_KEY_set_enc_flags +- Get and set flags for encoding EC_KEY structures + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); + void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); + +=head1 DESCRIPTION + +The format of the external representation of the public key written by +i2d_ECPrivateKey() (such as whether it is stored in a compressed form or not) is +described by the point_conversion_form. See L<EC_GROUP_copy(3)> +for a description of point_conversion_form. + +When reading a private key encoded without an associated public key (e.g. if +EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey() generates +the missing public key automatically. Private keys encoded without parameters +(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using +d2i_ECPrivateKey(). + +The functions EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the +value of the encoding flags for the B<key>. There are two encoding flags +currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags +define the behaviour of how the B<key> is converted into ASN1 in a call to +i2d_ECPrivateKey(). If EC_PKEY_NO_PARAMETERS is set then the public parameters for +the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is +set then the public key is not encoded along with the private key. + +=head1 RETURN VALUES + +EC_KEY_get_enc_flags() returns the value of the current encoding flags for the +EC_KEY. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, +L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>, +L<EC_POINT_add(3)>, +L<EC_GFp_simple_method(3)>, +L<d2i_ECPKParameters(3)>, +L<d2i_ECPrivateKey(3)> + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EC_KEY_new.pod b/openssl-1.1.0h/doc/crypto/EC_KEY_new.pod new file mode 100644 index 0000000..591529f --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EC_KEY_new.pod @@ -0,0 +1,183 @@ +=pod + +=head1 NAME + +EC_KEY_get_method, EC_KEY_set_method, +EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, +EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, +EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, +EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, +EC_KEY_get_conv_form, +EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, +EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates, +EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct, +EC_KEY_priv2buf - Functions for creating, destroying and manipulating +EC_KEY objects + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + EC_KEY *EC_KEY_new(void); + int EC_KEY_get_flags(const EC_KEY *key); + void EC_KEY_set_flags(EC_KEY *key, int flags); + void EC_KEY_clear_flags(EC_KEY *key, int flags); + EC_KEY *EC_KEY_new_by_curve_name(int nid); + void EC_KEY_free(EC_KEY *key); + EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); + EC_KEY *EC_KEY_dup(const EC_KEY *src); + int EC_KEY_up_ref(EC_KEY *key); + const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); + int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); + const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); + int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); + const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); + int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); + point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); + void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); + void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); + int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); + int EC_KEY_generate_key(EC_KEY *key); + int EC_KEY_check_key(const EC_KEY *key); + int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, + BIGNUM *x, BIGNUM *y); + const EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key); + int EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth); + + int EC_KEY_oct2key(EC_KEY *eckey, const unsigned char *buf, size_t len, + BN_CTX *ctx); + size_t EC_KEY_key2buf(const EC_KEY *eckey, point_conversion_form_t form, + unsigned char **pbuf, BN_CTX *ctx); + + int EC_KEY_oct2priv(EC_KEY *eckey, const unsigned char *buf, size_t len); + size_t EC_KEY_priv2oct(const EC_KEY *eckey, unsigned char *buf, size_t len); + + size_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf); + +=head1 DESCRIPTION + +An EC_KEY represents a public key and, optionally, the associated private +key. A new EC_KEY with no associated curve can be constructed by calling +EC_KEY_new(). The reference count for the newly created EC_KEY is initially +set to 1. A curve can be associated with the EC_KEY by calling +EC_KEY_set_group(). + +Alternatively a new EC_KEY can be constructed by calling +EC_KEY_new_by_curve_name() and supplying the nid of the associated curve. See +L<EC_GROUP_new(3)> for a description of curve names. This function simply +wraps calls to EC_KEY_new() and EC_GROUP_new_by_curve_name(). + +Calling EC_KEY_free() decrements the reference count for the EC_KEY object, +and if it has dropped to zero then frees the memory associated with it. If +B<key> is NULL nothing is done. + +EC_KEY_copy() copies the contents of the EC_KEY in B<src> into B<dest>. + +EC_KEY_dup() creates a new EC_KEY object and copies B<ec_key> into it. + +EC_KEY_up_ref() increments the reference count associated with the EC_KEY +object. + +EC_KEY_generate_key() generates a new public and private key for the supplied +B<eckey> object. B<eckey> must have an EC_GROUP object associated with it +before calling this function. The private key is a random integer (0 < priv_key +< order, where I<order> is the order of the EC_GROUP object). The public key is +an EC_POINT on the curve calculated by multiplying the generator for the +curve by the private key. + +EC_KEY_check_key() performs various sanity checks on the EC_KEY object to +confirm that it is valid. + +EC_KEY_set_public_key_affine_coordinates() sets the public key for B<key> based +on its affine co-ordinates; i.e., it constructs an EC_POINT object based on +the supplied B<x> and B<y> values and sets the public key to be this +EC_POINT. It also performs certain sanity checks on the key to confirm +that it is valid. + +The functions EC_KEY_get0_group(), EC_KEY_set_group(), +EC_KEY_get0_private_key(), EC_KEY_set_private_key(), EC_KEY_get0_public_key(), +and EC_KEY_set_public_key() get and set the EC_GROUP object, the private key, +and the EC_POINT public key for the B<key> respectively. + +The functions EC_KEY_get_conv_form() and EC_KEY_set_conv_form() get and set the +point_conversion_form for the B<key>. For a description of +point_conversion_forms please see L<EC_POINT_new(3)>. + +EC_KEY_set_flags() sets the flags in the B<flags> parameter on the EC_KEY +object. Any flags that are already set are left set. The flags currently +defined are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In +addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH. +EC_KEY_get_flags() returns the current flags that are set for this EC_KEY. +EC_KEY_clear_flags() clears the flags indicated by the B<flags> parameter; all +other flags are left in their existing state. + +EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object +(if set). Refer to L<EC_GROUP_copy(3)> for further information on the +asn1_flag. + +EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator +for faster point multiplication. See also L<EC_POINT_add(3)>. + +EC_KEY_oct2key() and EC_KEY_key2buf() are identical to the functions +EC_POINT_oct2point() and EC_KEY_point2buf() except they use the public key +EC_POINT in B<eckey>. + +EC_KEY_oct2priv() and EC_KEY_priv2oct() convert between the private key +component of B<eckey> and octet form. The octet form consists of the content +octets of the B<privateKey> OCTET STRING in an B<ECPrivateKey> ASN.1 structure. + +The function EC_KEY_priv2oct() must be supplied with a buffer long enough to +store the octet form. The return value provides the number of octets stored. +Calling the function with a NULL buffer will not perform the conversion but +will just return the required buffer length. + +The function EC_KEY_priv2buf() allocates a buffer of suitable length and writes +an EC_KEY to it in octet format. The allocated buffer is written to B<*pbuf> +and its length is returned. The caller must free up the allocated buffer with a +call to OPENSSL_free(). Since the allocated buffer value is written to B<*pbuf> +the B<pbuf> parameter B<MUST NOT> be B<NULL>. + +EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer. + +=head1 RETURN VALUES + +EC_KEY_new(), EC_KEY_new_by_curve_name() and EC_KEY_dup() return a pointer to +the newly created EC_KEY object, or NULL on error. + +EC_KEY_get_flags() returns the flags associated with the EC_KEY object as an +integer. + +EC_KEY_copy() returns a pointer to the destination key, or NULL on error. + +EC_KEY_up_ref(), EC_KEY_set_group(), EC_KEY_set_private_key(), +EC_KEY_set_public_key(), EC_KEY_precompute_mult(), EC_KEY_generate_key(), +EC_KEY_check_key(), EC_KEY_set_public_key_affine_coordinates(), +EC_KEY_oct2key() and EC_KEY_oct2priv() return 1 on success or 0 on error. + +EC_KEY_get0_group() returns the EC_GROUP associated with the EC_KEY. + +EC_KEY_get0_private_key() returns the private key associated with the EC_KEY. + +EC_KEY_get_conv_form() return the point_conversion_form for the EC_KEY. + +EC_KEY_key2buf(), EC_KEY_priv2oct() and EC_KEY_priv2buf() return the length +of the buffer or 0 on error. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, +L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>, +L<EC_POINT_add(3)>, +L<EC_GFp_simple_method(3)>, +L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EC_POINT_add.pod b/openssl-1.1.0h/doc/crypto/EC_POINT_add.pod new file mode 100644 index 0000000..6f3e230 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EC_POINT_add.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on EC_POINT objects + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); + int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); + int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); + int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); + int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); + int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); + int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); + int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); + int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); + int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); + int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); + int EC_GROUP_have_precompute_mult(const EC_GROUP *group); + + +=head1 DESCRIPTION + +EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the +result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>. + +EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>. + +The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not. + +EC_POINT_is_on_curve tests whether the supplied point is on the curve or not. + +EC_POINT_cmp compares the two supplied points and tests whether or not they are equal. + +The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine +co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be +forced. + +EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. The value B<n> may be NULL in which case the result is just B<q> * B<m>. + +EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value +B<n> may be NULL. + +The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst +EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)> for information +about the generator. + + +=head1 RETURN VALUES + +The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, +EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult. + +EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise. + +EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error. + +EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error. + +EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_new(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EC_POINT_new.pod b/openssl-1.1.0h/doc/crypto/EC_POINT_new.pod new file mode 100644 index 0000000..5ac41b3 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EC_POINT_new.pod @@ -0,0 +1,196 @@ +=pod + +=head1 NAME + +EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, +EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, +EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, +EC_POINT_set_to_infinity, +EC_POINT_get_Jprojective_coordinates_GFp, +EC_POINT_set_affine_coordinates_GFp, +EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, +EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, +EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, +EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, +EC_POINT_hex2point +- Functions for creating, destroying and manipulating EC_POINT objects + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + EC_POINT *EC_POINT_new(const EC_GROUP *group); + void EC_POINT_free(EC_POINT *point); + void EC_POINT_clear_free(EC_POINT *point); + int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); + EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); + const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); + int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); + int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, + EC_POINT *p, + const BIGNUM *x, const BIGNUM *y, + const BIGNUM *z, BN_CTX *ctx); + int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, + const EC_POINT *p, + BIGNUM *x, BIGNUM *y, BIGNUM *z, + BN_CTX *ctx); + int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, + const BIGNUM *x, const BIGNUM *y, + BN_CTX *ctx); + int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, + const EC_POINT *p, + BIGNUM *x, BIGNUM *y, BN_CTX *ctx); + int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, + EC_POINT *p, + const BIGNUM *x, int y_bit, + BN_CTX *ctx); + int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, + const BIGNUM *x, const BIGNUM *y, + BN_CTX *ctx); + int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, + const EC_POINT *p, + BIGNUM *x, BIGNUM *y, BN_CTX *ctx); + int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, + EC_POINT *p, + const BIGNUM *x, int y_bit, + BN_CTX *ctx); + size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, + point_conversion_form_t form, + unsigned char *buf, size_t len, BN_CTX *ctx); + size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point, + point_conversion_form_t form, + unsigned char **pbuf, BN_CTX *ctx); + int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, + const unsigned char *buf, size_t len, BN_CTX *ctx); + BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p, + point_conversion_form_t form, BIGNUM *bn, + BN_CTX *ctx); + EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn, + EC_POINT *p, BN_CTX *ctx); + char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p, + point_conversion_form_t form, BN_CTX *ctx); + EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex, + EC_POINT *p, BN_CTX *ctx); + + +=head1 DESCRIPTION + +An B<EC_POINT> structure represents a point on a curve. A new point is +constructed by calling the function EC_POINT_new() and providing the +B<group> object that the point relates to. + +EC_POINT_free() frees the memory associated with the B<EC_POINT>. +if B<point> is NULL nothing is done. + +EC_POINT_clear_free() destroys any sensitive data held within the EC_POINT and +then frees its memory. If B<point> is NULL nothing is done. + +EC_POINT_copy() copies the point B<src> into B<dst>. Both B<src> and B<dst> +must use the same B<EC_METHOD>. + +EC_POINT_dup() creates a new B<EC_POINT> object and copies the content from +B<src> to the newly created B<EC_POINT> object. + +EC_POINT_method_of() obtains the B<EC_METHOD> associated with B<point>. + +A valid point on a curve is the special point at infinity. A point is set to +be at infinity by calling EC_POINT_set_to_infinity(). + +The affine co-ordinates for a point describe a point in terms of its x and y +position. The functions EC_POINT_set_affine_coordinates_GFp() and +EC_POINT_set_affine_coordinates_GF2m() set the B<x> and B<y> co-ordinates for +the point B<p> defined over the curve given in B<group>. + +As well as the affine co-ordinates, a point can alternatively be described in +terms of its Jacobian projective co-ordinates (for Fp curves only). Jacobian +projective co-ordinates are expressed as three values x, y and z. Working in +this co-ordinate system provides more efficient point multiplication +operations. A mapping exists between Jacobian projective co-ordinates and +affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written +as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian +projective from affine co-ordinates is simple. The co-ordinate (x, y) is mapped +to (x, y, 1). To set or get the projective co-ordinates use +EC_POINT_set_Jprojective_coordinates_GFp() and +EC_POINT_get_Jprojective_coordinates_GFp() respectively. + +Points can also be described in terms of their compressed co-ordinates. For a +point (x, y), for any given value for x such that the point is on the curve +there will only ever be two possible values for y. Therefore a point can be set +using the EC_POINT_set_compressed_coordinates_GFp() and +EC_POINT_set_compressed_coordinates_GF2m() functions where B<x> is the x +co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two +possible values for y should be used. + +In addition B<EC_POINT> can be converted to and from various external +representations. The octet form is the binary encoding of the B<ECPoint> +structure (as defined in RFC5480 and used in certificates and TLS records): +only the content octets are present, the B<OCTET STRING> tag and length are +not included. B<BIGNUM> form is the octet form interpreted as a big endian +integer converted to a B<BIGNUM> structure. Hexadecimal form is the octet +form converted to a NULL terminated character string where each character +is one of the printable values 0-9 or A-F (or a-f). + +The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(), +EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from +and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively. + +The function EC_POINT_point2oct() must be supplied with a buffer long enough to +store the octet form. The return value provides the number of octets stored. +Calling the function with a NULL buffer will not perform the conversion but +will still return the required buffer length. + +The function EC_POINT_point2buf() allocates a buffer of suitable length and +writes an EC_POINT to it in octet format. The allocated buffer is written to +B<*pbuf> and its length is returned. The caller must free up the allocated +buffer with a call to OPENSSL_free(). Since the allocated buffer value is +written to B<*pbuf> the B<pbuf> parameter B<MUST NOT> be B<NULL>. + +The function EC_POINT_point2hex() will allocate sufficient memory to store the +hexadecimal string. It is the caller's responsibility to free this memory with +a subsequent call to OPENSSL_free(). + +=head1 RETURN VALUES + +EC_POINT_new() and EC_POINT_dup() return the newly allocated EC_POINT or NULL +on error. + +The following functions return 1 on success or 0 on error: EC_POINT_copy(), +EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(), +EC_POINT_get_Jprojective_coordinates_GFp(), +EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), +EC_POINT_set_compressed_coordinates_GFp(), +EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), +EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point(). + +EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT. + +EC_POINT_point2oct() and EC_POINT_point2buf() return the length of the required +buffer or 0 on error. + +EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on +error. + +EC_POINT_bn2point() returns the pointer to the EC_POINT supplied, or NULL on +error. + +EC_POINT_point2hex() returns a pointer to the hex string, or NULL on error. + +EC_POINT_hex2point() returns the pointer to the EC_POINT supplied, or NULL on +error. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ENGINE_add.pod b/openssl-1.1.0h/doc/crypto/ENGINE_add.pod new file mode 100644 index 0000000..d5a7d72 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ENGINE_add.pod @@ -0,0 +1,621 @@ +=pod + +=head1 NAME + +ENGINE_get_DH, ENGINE_get_DSA, ENGINE_get_ECDH, ENGINE_get_ECDSA, +ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH, +ENGINE_get_default_DSA, ENGINE_get_default_ECDH, +ENGINE_get_default_ECDSA, ENGINE_get_default_RAND, +ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first, +ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new, +ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests, +ENGINE_get_destroy_function, ENGINE_get_finish_function, +ENGINE_get_init_function, ENGINE_get_load_privkey_function, +ENGINE_get_load_pubkey_function, ENGINE_load_private_key, +ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id, +ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher, +ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable, +ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string, +ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init, +ENGINE_register_DH, ENGINE_register_DSA, ENGINE_register_ECDH, +ENGINE_register_ECDSA, ENGINE_register_RAND, ENGINE_register_RSA, +ENGINE_register_all_complete, ENGINE_register_ciphers, +ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove, +ENGINE_set_DH, ENGINE_set_DSA, ENGINE_set_ECDH, ENGINE_set_ECDSA, +ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers, +ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default, +ENGINE_set_default_DH, ENGINE_set_default_DSA, ENGINE_set_default_ECDH, +ENGINE_set_default_ECDSA, ENGINE_set_default_RAND, ENGINE_set_default_RSA, +ENGINE_set_default_ciphers, ENGINE_set_default_digests, +ENGINE_set_default_string, ENGINE_set_destroy_function, +ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags, +ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function, +ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref, +ENGINE_get_table_flags, ENGINE_cleanup, +ENGINE_load_builtin_engines, ENGINE_register_all_DH, +ENGINE_register_all_DSA, ENGINE_register_all_ECDH, +ENGINE_register_all_ECDSA, ENGINE_register_all_RAND, +ENGINE_register_all_RSA, ENGINE_register_all_ciphers, +ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH, +ENGINE_unregister_DSA, ENGINE_unregister_ECDH, ENGINE_unregister_ECDSA, +ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers, +ENGINE_unregister_digests +- ENGINE cryptographic module support + +=head1 SYNOPSIS + + #include <openssl/engine.h> + + ENGINE *ENGINE_get_first(void); + ENGINE *ENGINE_get_last(void); + ENGINE *ENGINE_get_next(ENGINE *e); + ENGINE *ENGINE_get_prev(ENGINE *e); + + int ENGINE_add(ENGINE *e); + int ENGINE_remove(ENGINE *e); + + ENGINE *ENGINE_by_id(const char *id); + + int ENGINE_init(ENGINE *e); + int ENGINE_finish(ENGINE *e); + + void ENGINE_load_builtin_engines(void); + + ENGINE *ENGINE_get_default_RSA(void); + ENGINE *ENGINE_get_default_DSA(void); + ENGINE *ENGINE_get_default_ECDH(void); + ENGINE *ENGINE_get_default_ECDSA(void); + ENGINE *ENGINE_get_default_DH(void); + ENGINE *ENGINE_get_default_RAND(void); + ENGINE *ENGINE_get_cipher_engine(int nid); + ENGINE *ENGINE_get_digest_engine(int nid); + + int ENGINE_set_default_RSA(ENGINE *e); + int ENGINE_set_default_DSA(ENGINE *e); + int ENGINE_set_default_ECDH(ENGINE *e); + int ENGINE_set_default_ECDSA(ENGINE *e); + int ENGINE_set_default_DH(ENGINE *e); + int ENGINE_set_default_RAND(ENGINE *e); + int ENGINE_set_default_ciphers(ENGINE *e); + int ENGINE_set_default_digests(ENGINE *e); + int ENGINE_set_default_string(ENGINE *e, const char *list); + + int ENGINE_set_default(ENGINE *e, unsigned int flags); + + unsigned int ENGINE_get_table_flags(void); + void ENGINE_set_table_flags(unsigned int flags); + + int ENGINE_register_RSA(ENGINE *e); + void ENGINE_unregister_RSA(ENGINE *e); + void ENGINE_register_all_RSA(void); + int ENGINE_register_DSA(ENGINE *e); + void ENGINE_unregister_DSA(ENGINE *e); + void ENGINE_register_all_DSA(void); + int ENGINE_register_ECDH(ENGINE *e); + void ENGINE_unregister_ECDH(ENGINE *e); + void ENGINE_register_all_ECDH(void); + int ENGINE_register_ECDSA(ENGINE *e); + void ENGINE_unregister_ECDSA(ENGINE *e); + void ENGINE_register_all_ECDSA(void); + int ENGINE_register_DH(ENGINE *e); + void ENGINE_unregister_DH(ENGINE *e); + void ENGINE_register_all_DH(void); + int ENGINE_register_RAND(ENGINE *e); + void ENGINE_unregister_RAND(ENGINE *e); + void ENGINE_register_all_RAND(void); + int ENGINE_register_ciphers(ENGINE *e); + void ENGINE_unregister_ciphers(ENGINE *e); + void ENGINE_register_all_ciphers(void); + int ENGINE_register_digests(ENGINE *e); + void ENGINE_unregister_digests(ENGINE *e); + void ENGINE_register_all_digests(void); + int ENGINE_register_complete(ENGINE *e); + int ENGINE_register_all_complete(void); + + int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); + int ENGINE_cmd_is_executable(ENGINE *e, int cmd); + int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, + long i, void *p, void (*f)(void), int cmd_optional); + int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, + int cmd_optional); + + ENGINE *ENGINE_new(void); + int ENGINE_free(ENGINE *e); + int ENGINE_up_ref(ENGINE *e); + + int ENGINE_set_id(ENGINE *e, const char *id); + int ENGINE_set_name(ENGINE *e, const char *name); + int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); + int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); + int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth); + int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth); + int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); + int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); + int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); + int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); + int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); + int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); + int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); + int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); + int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); + int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); + int ENGINE_set_flags(ENGINE *e, int flags); + int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); + + const char *ENGINE_get_id(const ENGINE *e); + const char *ENGINE_get_name(const ENGINE *e); + const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); + const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); + const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e); + const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e); + const DH_METHOD *ENGINE_get_DH(const ENGINE *e); + const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); + ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); + ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); + ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); + ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); + ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); + ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); + ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); + ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); + const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); + const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); + int ENGINE_get_flags(const ENGINE *e); + const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); + + EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, + UI_METHOD *ui_method, void *callback_data); + EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, + UI_METHOD *ui_method, void *callback_data); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + void ENGINE_cleanup(void) + #endif + +=head1 DESCRIPTION + +These functions create, manipulate, and use cryptographic modules in the +form of B<ENGINE> objects. These objects act as containers for +implementations of cryptographic algorithms, and support a +reference-counted mechanism to allow them to be dynamically loaded in and +out of the running application. + +The cryptographic functionality that can be provided by an B<ENGINE> +implementation includes the following abstractions; + + RSA_METHOD - for providing alternative RSA implementations + DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, + - similarly for other OpenSSL APIs + EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') + EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') + key-loading - loading public and/or private EVP_PKEY keys + +=head2 Reference counting and handles + +Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be +treated as handles - ie. not only as pointers, but also as references to +the underlying ENGINE object. Ie. one should obtain a new reference when +making copies of an ENGINE pointer if the copies will be used (and +released) independently. + +ENGINE objects have two levels of reference-counting to match the way in +which the objects are used. At the most basic level, each ENGINE pointer is +inherently a B<structural> reference - a structural reference is required +to use the pointer value at all, as this kind of reference is a guarantee +that the structure can not be deallocated until the reference is released. + +However, a structural reference provides no guarantee that the ENGINE is +initialised and able to use any of its cryptographic +implementations. Indeed it's quite possible that most ENGINEs will not +initialise at all in typical environments, as ENGINEs are typically used to +support specialised hardware. To use an ENGINE's functionality, you need a +B<functional> reference. This kind of reference can be considered a +specialised form of structural reference, because each functional reference +implicitly contains a structural reference as well - however to avoid +difficult-to-find programming bugs, it is recommended to treat the two +kinds of reference independently. If you have a functional reference to an +ENGINE, you have a guarantee that the ENGINE has been initialised and +is ready to perform cryptographic operations, and will remain initialised +until after you have released your reference. + +I<Structural references> + +This basic type of reference is used for instantiating new ENGINEs, +iterating across OpenSSL's internal linked-list of loaded +ENGINEs, reading information about an ENGINE, etc. Essentially a structural +reference is sufficient if you only need to query or manipulate the data of +an ENGINE implementation rather than use its functionality. + +The ENGINE_new() function returns a structural reference to a new (empty) +ENGINE object. There are other ENGINE API functions that return structural +references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), +ENGINE_get_next(), ENGINE_get_prev(). All structural references should be +released by a corresponding to call to the ENGINE_free() function - the +ENGINE object itself will only actually be cleaned up and deallocated when +the last structural reference is released. + +It should also be noted that many ENGINE API function calls that accept a +structural reference will internally obtain another reference - typically +this happens whenever the supplied ENGINE will be needed by OpenSSL after +the function has returned. Eg. the function to add a new ENGINE to +OpenSSL's internal list is ENGINE_add() - if this function returns success, +then OpenSSL will have stored a new structural reference internally so the +caller is still responsible for freeing their own reference with +ENGINE_free() when they are finished with it. In a similar way, some +functions will automatically release the structural reference passed to it +if part of the function's job is to do so. Eg. the ENGINE_get_next() and +ENGINE_get_prev() functions are used for iterating across the internal +ENGINE list - they will return a new structural reference to the next (or +previous) ENGINE in the list or NULL if at the end (or beginning) of the +list, but in either case the structural reference passed to the function is +released on behalf of the caller. + +To clarify a particular function's handling of references, one should +always consult that function's documentation "man" page, or failing that +the openssl/engine.h header file includes some hints. + +I<Functional references> + +As mentioned, functional references exist when the cryptographic +functionality of an ENGINE is required to be available. A functional +reference can be obtained in one of two ways; from an existing structural +reference to the required ENGINE, or by asking OpenSSL for the default +operational ENGINE for a given cryptographic purpose. + +To obtain a functional reference from an existing structural reference, +call the ENGINE_init() function. This returns zero if the ENGINE was not +already operational and couldn't be successfully initialised (eg. lack of +system drivers, no special hardware attached, etc), otherwise it will +return non-zero to indicate that the ENGINE is now operational and will +have allocated a new B<functional> reference to the ENGINE. All functional +references are released by calling ENGINE_finish() (which removes the +implicit structural reference as well). + +The second way to get a functional reference is by asking OpenSSL for a +default implementation for a given task, eg. by ENGINE_get_default_RSA(), +ENGINE_get_default_cipher_engine(), etc. These are discussed in the next +section, though they are not usually required by application programmers as +they are used automatically when creating and using the relevant +algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. + +=head2 Default implementations + +For each supported abstraction, the ENGINE code maintains an internal table +of state to control which implementations are available for a given +abstraction and which should be used by default. These implementations are +registered in the tables and indexed by an 'nid' value, because +abstractions like EVP_CIPHER and EVP_DIGEST support many distinct +algorithms and modes, and ENGINEs can support arbitrarily many of them. +In the case of other abstractions like RSA, DSA, etc, there is only one +"algorithm" so all implementations implicitly register using the same 'nid' +index. + +When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg. +when calling RSA_new_method(NULL)), a "get_default" call will be made to the +ENGINE subsystem to process the corresponding state table and return a +functional reference to an initialised ENGINE whose implementation should be +used. If no ENGINE should (or can) be used, it will return NULL and the caller +will operate with a NULL ENGINE handle - this usually equates to using the +conventional software implementation. In the latter case, OpenSSL will from +then on behave the way it used to before the ENGINE API existed. + +Each state table has a flag to note whether it has processed this +"get_default" query since the table was last modified, because to process +this question it must iterate across all the registered ENGINEs in the +table trying to initialise each of them in turn, in case one of them is +operational. If it returns a functional reference to an ENGINE, it will +also cache another reference to speed up processing future queries (without +needing to iterate across the table). Likewise, it will cache a NULL +response if no ENGINE was available so that future queries won't repeat the +same iteration unless the state table changes. This behaviour can also be +changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using +ENGINE_set_table_flags()), no attempted initialisations will take place, +instead the only way for the state table to return a non-NULL ENGINE to the +"get_default" query will be if one is expressly set in the table. Eg. +ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except +that it also sets the state table's cached response for the "get_default" +query. In the case of abstractions like EVP_CIPHER, where implementations are +indexed by 'nid', these flags and cached-responses are distinct for each 'nid' +value. + +=head2 Application requirements + +This section will explain the basic things an application programmer should +support to make the most useful elements of the ENGINE functionality +available to the user. The first thing to consider is whether the +programmer wishes to make alternative ENGINE modules available to the +application and user. OpenSSL maintains an internal linked list of +"visible" ENGINEs from which it has to operate - at start-up, this list is +empty and in fact if an application does not call any ENGINE API calls and +it uses static linking against openssl, then the resulting application +binary will not contain any alternative ENGINE code at all. So the first +consideration is whether any/all available ENGINE implementations should be +made visible to OpenSSL - this is controlled by calling the various "load" +functions. + +Having called any of these functions, ENGINE objects would have been +dynamically allocated and populated with these implementations and linked +into OpenSSL's internal linked list. At this point it is important to +mention an important API function; + + void ENGINE_cleanup(void) + +If no ENGINE API functions are called at all in an application, then there +are no inherent memory leaks to worry about from the ENGINE functionality. +However, prior to OpenSSL 1.1.0 if any ENGINEs are loaded, even if they are +never registered or used, it was necessary to use the ENGINE_cleanup() function +to correspondingly cleanup before program exit, if the caller wishes to avoid +memory leaks. This mechanism used an internal callback registration table +so that any ENGINE API functionality that knows it requires cleanup can +register its cleanup details to be called during ENGINE_cleanup(). This +approach allowed ENGINE_cleanup() to clean up after any ENGINE functionality +at all that your program uses, yet doesn't automatically create linker +dependencies to all possible ENGINE functionality - only the cleanup +callbacks required by the functionality you do use will be required by the +linker. From OpenSSL 1.1.0 it is no longer necessary to explicitly call +ENGINE_cleanup and this function is deprecated. Cleanup automatically takes +place at program exit. + +The fact that ENGINEs are made visible to OpenSSL (and thus are linked into +the program and loaded into memory at run-time) does not mean they are +"registered" or called into use by OpenSSL automatically - that behaviour +is something for the application to control. Some applications +will want to allow the user to specify exactly which ENGINE they want used +if any is to be used at all. Others may prefer to load all support and have +OpenSSL automatically use at run-time any ENGINE that is able to +successfully initialise - ie. to assume that this corresponds to +acceleration hardware attached to the machine or some such thing. There are +probably numerous other ways in which applications may prefer to handle +things, so we will simply illustrate the consequences as they apply to a +couple of simple cases and leave developers to consider these and the +source code to openssl's builtin utilities as guides. + +I<Using a specific ENGINE implementation> + +Here we'll assume an application has been configured by its user or admin +to want to use the "ACME" ENGINE if it is available in the version of +OpenSSL the application was compiled with. If it is available, it should be +used by default for all RSA, DSA, and symmetric cipher operations, otherwise +OpenSSL should use its builtin software as per usual. The following code +illustrates how to approach this; + + ENGINE *e; + const char *engine_id = "ACME"; + ENGINE_load_builtin_engines(); + e = ENGINE_by_id(engine_id); + if(!e) + /* the engine isn't available */ + return; + if(!ENGINE_init(e)) { + /* the engine couldn't initialise, release 'e' */ + ENGINE_free(e); + return; + } + if(!ENGINE_set_default_RSA(e)) + /* This should only happen when 'e' can't initialise, but the previous + * statement suggests it did. */ + abort(); + ENGINE_set_default_DSA(e); + ENGINE_set_default_ciphers(e); + /* Release the functional reference from ENGINE_init() */ + ENGINE_finish(e); + /* Release the structural reference from ENGINE_by_id() */ + ENGINE_free(e); + +I<Automatically using builtin ENGINE implementations> + +Here we'll assume we want to load and register all ENGINE implementations +bundled with OpenSSL, such that for any cryptographic algorithm required by +OpenSSL - if there is an ENGINE that implements it and can be initialised, +it should be used. The following code illustrates how this can work; + + /* Load all bundled ENGINEs into memory and make them visible */ + ENGINE_load_builtin_engines(); + /* Register all of them for every algorithm they collectively implement */ + ENGINE_register_all_complete(); + +That's all that's required. Eg. the next time OpenSSL tries to set up an +RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to +ENGINE_init() and if any of those succeed, that ENGINE will be set as the +default for RSA use from then on. + +=head2 Advanced configuration support + +There is a mechanism supported by the ENGINE framework that allows each +ENGINE implementation to define an arbitrary set of configuration +"commands" and expose them to OpenSSL and any applications based on +OpenSSL. This mechanism is entirely based on the use of name-value pairs +and assumes ASCII input (no unicode or UTF for now!), so it is ideal if +applications want to provide a transparent way for users to provide +arbitrary configuration "directives" directly to such ENGINEs. It is also +possible for the application to dynamically interrogate the loaded ENGINE +implementations for the names, descriptions, and input flags of their +available "control commands", providing a more flexible configuration +scheme. However, if the user is expected to know which ENGINE device he/she +is using (in the case of specialised hardware, this goes without saying) +then applications may not need to concern themselves with discovering the +supported control commands and simply prefer to pass settings into ENGINEs +exactly as they are provided by the user. + +Before illustrating how control commands work, it is worth mentioning what +they are typically used for. Broadly speaking there are two uses for +control commands; the first is to provide the necessary details to the +implementation (which may know nothing at all specific to the host system) +so that it can be initialised for use. This could include the path to any +driver or config files it needs to load, required network addresses, +smart-card identifiers, passwords to initialise protected devices, +logging information, etc etc. This class of commands typically needs to be +passed to an ENGINE B<before> attempting to initialise it, ie. before +calling ENGINE_init(). The other class of commands consist of settings or +operations that tweak certain behaviour or cause certain operations to take +place, and these commands may work either before or after ENGINE_init(), or +in some cases both. ENGINE implementations should provide indications of +this in the descriptions attached to builtin control commands and/or in +external product documentation. + +I<Issuing control commands to an ENGINE> + +Let's illustrate by example; a function for which the caller supplies the +name of the ENGINE it wishes to use, a table of string-pairs for use before +initialisation, and another table for use after initialisation. Note that +the string-pairs used for control commands consist of a command "name" +followed by the command "parameter" - the parameter could be NULL in some +cases but the name can not. This function should initialise the ENGINE +(issuing the "pre" commands beforehand and the "post" commands afterwards) +and set it as the default for everything except RAND and then return a +boolean success or failure. + + int generic_load_engine_fn(const char *engine_id, + const char **pre_cmds, int pre_num, + const char **post_cmds, int post_num) + { + ENGINE *e = ENGINE_by_id(engine_id); + if (!e) return 0; + while (pre_num--) { + if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { + fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, + pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); + ENGINE_free(e); + return 0; + } + pre_cmds += 2; + } + if (!ENGINE_init(e)) { + fprintf(stderr, "Failed initialisation\n"); + ENGINE_free(e); + return 0; + } + /* ENGINE_init() returned a functional reference, so free the structural + * reference from ENGINE_by_id(). */ + ENGINE_free(e); + while(post_num--) { + if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { + fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, + post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); + ENGINE_finish(e); + return 0; + } + post_cmds += 2; + } + ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); + /* Success */ + return 1; + } + +Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can +relax the semantics of the function - if set non-zero it will only return +failure if the ENGINE supported the given command name but failed while +executing it, if the ENGINE doesn't support the command name it will simply +return success without doing anything. In this case we assume the user is +only supplying commands specific to the given ENGINE so we set this to +FALSE. + +I<Discovering supported control commands> + +It is possible to discover at run-time the names, numerical-ids, descriptions +and input parameters of the control commands supported by an ENGINE using a +structural reference. Note that some control commands are defined by OpenSSL +itself and it will intercept and handle these control commands on behalf of the +ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command. +openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands +implemented by ENGINEs should be numbered from. Any command value lower than +this symbol is considered a "generic" command is handled directly by the +OpenSSL core routines. + +It is using these "core" control commands that one can discover the control +commands implemented by a given ENGINE, specifically the commands: + + ENGINE_HAS_CTRL_FUNCTION + ENGINE_CTRL_GET_FIRST_CMD_TYPE + ENGINE_CTRL_GET_NEXT_CMD_TYPE + ENGINE_CTRL_GET_CMD_FROM_NAME + ENGINE_CTRL_GET_NAME_LEN_FROM_CMD + ENGINE_CTRL_GET_NAME_FROM_CMD + ENGINE_CTRL_GET_DESC_LEN_FROM_CMD + ENGINE_CTRL_GET_DESC_FROM_CMD + ENGINE_CTRL_GET_CMD_FLAGS + +Whilst these commands are automatically processed by the OpenSSL framework code, +they use various properties exposed by each ENGINE to process these +queries. An ENGINE has 3 properties it exposes that can affect how this behaves; +it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in +the ENGINE's flags, and it can expose an array of control command descriptions. +If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will +simply pass all these "core" control commands directly to the ENGINE's ctrl() +handler (and thus, it must have supplied one), so it is up to the ENGINE to +reply to these "discovery" commands itself. If that flag is not set, then the +OpenSSL framework code will work with the following rules; + + if no ctrl() handler supplied; + ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), + all other commands fail. + if a ctrl() handler was supplied but no array of control commands; + ENGINE_HAS_CTRL_FUNCTION returns TRUE, + all other commands fail. + if a ctrl() handler and array of control commands was supplied; + ENGINE_HAS_CTRL_FUNCTION returns TRUE, + all other commands proceed processing ... + +If the ENGINE's array of control commands is empty then all other commands will +fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of +the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the +identifier of a command supported by the ENGINE and returns the next command +identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string +name for a command and returns the corresponding identifier or fails if no such +command name exists, and the remaining commands take a command identifier and +return properties of the corresponding commands. All except +ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, +or populate a supplied character buffer with a copy of the command name or +description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following +possible values: + + ENGINE_CMD_FLAG_NUMERIC + ENGINE_CMD_FLAG_STRING + ENGINE_CMD_FLAG_NO_INPUT + ENGINE_CMD_FLAG_INTERNAL + +If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely +informational to the caller - this flag will prevent the command being usable +for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). +"INTERNAL" commands are not intended to be exposed to text-based configuration +by applications, administrations, users, etc. These can support arbitrary +operations via ENGINE_ctrl(), including passing to and/or from the control +commands data of any arbitrary type. These commands are supported in the +discovery mechanisms simply to allow applications to determine if an ENGINE +supports certain specific commands it might want to use (eg. application "foo" +might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - +and ENGINE could therefore decide whether or not to support this "foo"-specific +extension). + +=head1 ENVIRONMENT + +=over 4 + +=item B<OPENSSL_ENGINES> + +The path to the engines directory. + +=back + +=head1 SEE ALSO + +L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<dsa(3)>, L<dh(3)>, L<rand(3)> + +=head1 HISTORY + +ENGINE_cleanup(), ENGINE_load_openssl(), ENGINE_load_dynamic(), and +ENGINE_load_cryptodev() were deprecated in OpenSSL 1.1.0 by +OPENSSL_init_crypto(). + +=head1 COPYRIGHT + +Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_GET_LIB.pod b/openssl-1.1.0h/doc/crypto/ERR_GET_LIB.pod new file mode 100644 index 0000000..5602a8e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_GET_LIB.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON, ERR_FATAL_ERROR +- get information from error codes + +=head1 SYNOPSIS + + #include <openssl/err.h> + + int ERR_GET_LIB(unsigned long e); + + int ERR_GET_FUNC(unsigned long e); + + int ERR_GET_REASON(unsigned long e); + + int ERR_FATAL_ERROR(unsigned long e); + +=head1 DESCRIPTION + +The error code returned by ERR_get_error() consists of a library +number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC() +and ERR_GET_REASON() can be used to extract these. + +ERR_FATAL_ERROR() indicates whether a given error code is a fatal error. + +The library number and function code describe where the error +occurred, the reason code is the information about what went wrong. + +Each sub-library of OpenSSL has a unique library number; function and +reason codes are unique within each sub-library. Note that different +libraries may use the same value to signal different functions and +reasons. + +B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally +unique. However, when checking for sub-library specific reason codes, +be sure to also compare the library number. + +ERR_GET_LIB(), ERR_GET_FUNC(), ERR_GET_REASON(), and ERR_FATAL_ERROR() + are macros. + +=head1 RETURN VALUES + +The library number, function code, reason code, and whether the error +is fatal, respectively. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 HISTORY + +ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in +all versions of OpenSSL. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_clear_error.pod b/openssl-1.1.0h/doc/crypto/ERR_clear_error.pod new file mode 100644 index 0000000..c876615 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_clear_error.pod @@ -0,0 +1,34 @@ +=pod + +=head1 NAME + +ERR_clear_error - clear the error queue + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_clear_error(void); + +=head1 DESCRIPTION + +ERR_clear_error() empties the current thread's error queue. + +=head1 RETURN VALUES + +ERR_clear_error() has no return value. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_error_string.pod b/openssl-1.1.0h/doc/crypto/ERR_error_string.pod new file mode 100644 index 0000000..695eaf2 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_error_string.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +ERR_error_string, ERR_error_string_n, ERR_lib_error_string, +ERR_func_error_string, ERR_reason_error_string - obtain human-readable +error message + +=head1 SYNOPSIS + + #include <openssl/err.h> + + char *ERR_error_string(unsigned long e, char *buf); + void ERR_error_string_n(unsigned long e, char *buf, size_t len); + + const char *ERR_lib_error_string(unsigned long e); + const char *ERR_func_error_string(unsigned long e); + const char *ERR_reason_error_string(unsigned long e); + +=head1 DESCRIPTION + +ERR_error_string() generates a human-readable string representing the +error code I<e>, and places it at I<buf>. I<buf> must be at least 256 +bytes long. If I<buf> is B<NULL>, the error string is placed in a +static buffer. +Note that this function is not thread-safe and does no checks on the size +of the buffer; use ERR_error_string_n() instead. + +ERR_error_string_n() is a variant of ERR_error_string() that writes +at most I<len> characters (including the terminating 0) +and truncates the string if necessary. +For ERR_error_string_n(), I<buf> may not be B<NULL>. + +The string will have the following format: + + error:[error code]:[library name]:[function name]:[reason string] + +I<error code> is an 8 digit hexadecimal number, I<library name>, +I<function name> and I<reason string> are ASCII text. + +ERR_lib_error_string(), ERR_func_error_string() and +ERR_reason_error_string() return the library name, function +name and reason string respectively. + +If there is no text string registered for the given error code, +the error string will contain the numeric code. + +L<ERR_print_errors(3)> can be used to print +all error codes currently in the queue. + +=head1 RETURN VALUES + +ERR_error_string() returns a pointer to a static buffer containing the +string if I<buf> B<== NULL>, I<buf> otherwise. + +ERR_lib_error_string(), ERR_func_error_string() and +ERR_reason_error_string() return the strings, and B<NULL> if +none is registered for the error code. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<ERR_print_errors(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_get_error.pod b/openssl-1.1.0h/doc/crypto/ERR_get_error.pod new file mode 100644 index 0000000..3b223c9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_get_error.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +ERR_get_error, ERR_peek_error, ERR_peek_last_error, +ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line, +ERR_get_error_line_data, ERR_peek_error_line_data, +ERR_peek_last_error_line_data - obtain error code and data + +=head1 SYNOPSIS + + #include <openssl/err.h> + + unsigned long ERR_get_error(void); + unsigned long ERR_peek_error(void); + unsigned long ERR_peek_last_error(void); + + unsigned long ERR_get_error_line(const char **file, int *line); + unsigned long ERR_peek_error_line(const char **file, int *line); + unsigned long ERR_peek_last_error_line(const char **file, int *line); + + unsigned long ERR_get_error_line_data(const char **file, int *line, + const char **data, int *flags); + unsigned long ERR_peek_error_line_data(const char **file, int *line, + const char **data, int *flags); + unsigned long ERR_peek_last_error_line_data(const char **file, int *line, + const char **data, int *flags); + +=head1 DESCRIPTION + +ERR_get_error() returns the earliest error code from the thread's error +queue and removes the entry. This function can be called repeatedly +until there are no more error codes to return. + +ERR_peek_error() returns the earliest error code from the thread's +error queue without modifying it. + +ERR_peek_last_error() returns the latest error code from the thread's +error queue without modifying it. + +See L<ERR_GET_LIB(3)> for obtaining information about +location and reason of the error, and +L<ERR_error_string(3)> for human-readable error +messages. + +ERR_get_error_line(), ERR_peek_error_line() and +ERR_peek_last_error_line() are the same as the above, but they +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_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> 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 + +The error code, or 0 if there is no error in the queue. + +=head1 SEE ALSO + +L<ERR_error_string(3)>, +L<ERR_GET_LIB(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_load_crypto_strings.pod b/openssl-1.1.0h/doc/crypto/ERR_load_crypto_strings.pod new file mode 100644 index 0000000..56d91d5 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_load_crypto_strings.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - +load and free error strings + +=head1 SYNOPSIS + +Deprecated: + + #include <openssl/err.h> + + #if OPENSSL_API_COMPAT < 0x10100000L + void ERR_load_crypto_strings(void); + void ERR_free_strings(void); + #endif + + #include <openssl/ssl.h> + + #if OPENSSL_API_COMPAT < 0x10100000L + void SSL_load_error_strings(void); + #endif + +=head1 DESCRIPTION + +All of the following functions are deprecated from OpenSSL 1.1.0. No explicit +initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)> +and L<OPENSSL_init_ssl(3)>. + +ERR_load_crypto_strings() registers the error strings for all +B<libcrypto> functions. SSL_load_error_strings() does the same, +but also registers the B<libssl> error strings. + +In versions of OpenSSL prior to 1.1.0 ERR_free_strings() freed all previously +loaded error strings. However from OpenSSL 1.1.0 it does nothing. + +=head1 RETURN VALUES + +ERR_load_crypto_strings(), SSL_load_error_strings() and +ERR_free_strings() return no values. + +=head1 SEE ALSO + +L<ERR_error_string(3)> + +=head1 HISTORY + +The ERR_load_crypto_strings(), SSL_load_error_strings(), and +ERR_free_strings() functions were deprecated in OpenSSL 1.1.0 by +OPENSSL_init_crypto() and OPENSSL_init_ssl(). + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_load_strings.pod b/openssl-1.1.0h/doc/crypto/ERR_load_strings.pod new file mode 100644 index 0000000..ee8de2c --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_load_strings.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load +arbitrary error strings + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_load_strings(int lib, ERR_STRING_DATA str[]); + + int ERR_get_next_error_library(void); + + unsigned long ERR_PACK(int lib, int func, int reason); + +=head1 DESCRIPTION + +ERR_load_strings() registers error strings for library number B<lib>. + +B<str> is an array of error string data: + + typedef struct ERR_string_data_st + { + unsigned long error; + char *string; + } ERR_STRING_DATA; + +The error code is generated from the library number and a function and +reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>). +ERR_PACK() is a macro. + +The last entry in the array is {0,0}. + +ERR_get_next_error_library() can be used to assign library numbers +to user libraries at runtime. + +=head1 RETURN VALUE + +ERR_load_strings() returns no value. ERR_PACK() return the error code. +ERR_get_next_error_library() returns zero on failure, otherwise a new +library number. + +=head1 SEE ALSO + +L<ERR_load_strings(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_print_errors.pod b/openssl-1.1.0h/doc/crypto/ERR_print_errors.pod new file mode 100644 index 0000000..134b374 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_print_errors.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + +ERR_print_errors, ERR_print_errors_fp, ERR_print_errors_cb +- print error messages + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_print_errors(BIO *bp); + void ERR_print_errors_fp(FILE *fp); + void ERR_print_errors_cb(int (*cb)(const char *str, size_t len, void *u), + void *u) + + +=head1 DESCRIPTION + +ERR_print_errors() is a convenience function that prints the error +strings for all errors that OpenSSL has recorded to B<bp>, thus +emptying the error queue. + +ERR_print_errors_fp() is the same, except that the output goes to a +B<FILE>. + +ERR_print_errors_cb() is the same, except that the callback function, +B<cb>, is called for each error line with the string, length, and userdata +B<u> as the callback parameters. + +The error strings will have the following format: + + [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message] + +I<error code> is an 8 digit hexadecimal number. I<library name>, +I<function name> and I<reason string> are ASCII text, as is I<optional +text message> if one was set for the respective error code. + +If there is no text string registered for the given error code, +the error string will contain the numeric code. + +=head1 RETURN VALUES + +ERR_print_errors() and ERR_print_errors_fp() return no values. + +=head1 SEE ALSO + +L<ERR_error_string(3)>, +L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_put_error.pod b/openssl-1.1.0h/doc/crypto/ERR_put_error.pod new file mode 100644 index 0000000..14695ba --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_put_error.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +ERR_put_error, ERR_add_error_data - record an error + +=head1 SYNOPSIS + + #include <openssl/err.h> + + void ERR_put_error(int lib, int func, int reason, const char *file, + int line); + + void ERR_add_error_data(int num, ...); + void ERR_add_error_data(int num, va_list arg); + +=head1 DESCRIPTION + +ERR_put_error() adds an error code to the thread's error queue. It +signals that the error of reason code B<reason> occurred in function +B<func> of library B<lib>, in line number B<line> of B<file>. +This function is usually called by a macro. + +ERR_add_error_data() associates the concatenation of its B<num> string +arguments with the error code added last. +ERR_add_error_vdata() is similar except the argument is a B<va_list>. + +L<ERR_load_strings(3)> can be used to register +error strings so that the application can a generate human-readable +error messages for the error code. + +=head2 Reporting errors + +Each sub-library has a specific macro XXXerr() that is used to report +errors. Its first argument is a function code B<XXX_F_...>, the second +argument is a reason code B<XXX_R_...>. Function codes are derived +from the function names; reason codes consist of textual error +descriptions. For example, the function ssl3_read_bytes() reports a +"handshake failure" as follows: + + SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE); + +Function and reason codes should consist of upper case characters, +numbers and underscores only. The error file generation script translates +function codes into function names by looking in the header files +for an appropriate function name, if none is found it just uses +the capitalized form such as "SSL3_READ_BYTES" in the above example. + +The trailing section of a reason code (after the "_R_") is translated +into lower case and underscores changed to spaces. + +Although a library will normally report errors using its own specific +XXXerr macro, another library's macro can be used. This is normally +only done when a library wants to include ASN1 code which must use +the ASN1err() macro. + + +=head1 RETURN VALUES + +ERR_put_error() and ERR_add_error_data() return +no values. + +=head1 SEE ALSO + +L<ERR_load_strings(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_remove_state.pod b/openssl-1.1.0h/doc/crypto/ERR_remove_state.pod new file mode 100644 index 0000000..617b4b7 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_remove_state.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +ERR_remove_thread_state, ERR_remove_state - DEPRECATED + +=head1 SYNOPSIS + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10000000L + void ERR_remove_state(unsigned long pid); + #endif + + #if OPENSSL_API_COMPAT < 0x10100000L + void ERR_remove_thread_state(void *); + #endif + +=head1 DESCRIPTION + +The functions described here were used to free the error queue +associated with the current or specified thread. + +They are now deprecated and do nothing, as the OpenSSL libraries now +normally do all thread initialisation and deinitialisation +automatically (see L<OPENSSL_init_crypto(3)>). + +=head1 RETURN VALUE + +The functions described here return no value. + +=head1 SEE ALSO + +LL<OPENSSL_init_crypto(3)> + +=head1 HISTORY + +ERR_remove_state() was deprecated in OpenSSL 1.0.0 when +ERR_remove_thread_state() was introduced. + +ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0 when the +thread handling functionality was entirely rewritten. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ERR_set_mark.pod b/openssl-1.1.0h/doc/crypto/ERR_set_mark.pod new file mode 100644 index 0000000..b3afea8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ERR_set_mark.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark + +=head1 SYNOPSIS + + #include <openssl/err.h> + + int ERR_set_mark(void); + + int ERR_pop_to_mark(void); + +=head1 DESCRIPTION + +ERR_set_mark() sets a mark on the current topmost error record if there +is one. + +ERR_pop_to_mark() will pop the top of the error stack until a mark is found. +The mark is then removed. If there is no mark, the whole stack is removed. + +=head1 RETURN VALUES + +ERR_set_mark() returns 0 if the error stack is empty, otherwise 1. + +ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which +implies that the stack became empty, otherwise 1. + +=head1 COPYRIGHT + +Copyright 2003-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_BytesToKey.pod b/openssl-1.1.0h/doc/crypto/EVP_BytesToKey.pod new file mode 100644 index 0000000..728c94e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_BytesToKey.pod @@ -0,0 +1,78 @@ +=pod + +=head1 NAME + +EVP_BytesToKey - password based encryption routine + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md, + const unsigned char *salt, + const unsigned char *data, int datal, int count, + unsigned char *key, unsigned char *iv); + +=head1 DESCRIPTION + +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> 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> +and B<iv> respectively. + +=head1 NOTES + +A typical application of this function is to derive keying material for an +encryption algorithm from a password in the B<data> parameter. + +Increasing the B<count> parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. + +If the total key and IV length is less than the digest length and +B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5 +otherwise a non standard extension is used to derive the extra data. + +Newer applications should use a more modern algorithm such as PBKDF2 as +defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC. + +=head1 KEY DERIVATION ALGORITHM + +The key and IV is derived by concatenating D_1, D_2, etc until +enough data is available for the key and IV. D_i is defined as: + + D_i = HASH^count(D_(i-1) || data || salt) + +where || denotes concatenation, D_0 is empty, HASH is the digest +algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) +is HASH(HASH(data)) and so on. + +The initial bytes are used for the key and the subsequent bytes for +the IV. + +=head1 RETURN VALUES + +If B<data> is NULL, then EVP_BytesToKey() returns the number of bytes +needed to store the derived key. +Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes, +or 0 on error. + +=head1 SEE ALSO + +L<evp(3)>, L<rand(3)>, +L<PKCS5_PBKDF2_HMAC(3)>, +L<EVP_EncryptInit(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod b/openssl-1.1.0h/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod new file mode 100644 index 0000000..3a57fcd --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +EVP_CIPHER_CTX_get_cipher_data, EVP_CIPHER_CTX_set_cipher_data - Routines to +inspect and modify EVP_CIPHER_CTX objects + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void *EVP_CIPHER_CTX_get_cipher_data(const EVP_CIPHER_CTX *ctx); + void *EVP_CIPHER_CTX_set_cipher_data(EVP_CIPHER_CTX *ctx, void *cipher_data); + +=head1 DESCRIPTION + +The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the cipher +data relevant to EVP_CIPHER_CTX. The contents of this data is specific to the +particular implementation of the cipher. For example this data can be used by +engines to store engine specific information. The data is automatically +allocated and freed by OpenSSL, so applications and engines should not normally +free this directly (but see below). + +The EVP_CIPHER_CTX_set_cipher_data() function allows an application or engine to +replace the cipher data with new data. A pointer to any existing cipher data is +returned from this function. If the old data is no longer required then it +should be freed through a call to OPENSSL_free(). + +=head1 RETURN VALUES + +The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the current +cipher data for the EVP_CIPHER_CTX. + +The EVP_CIPHER_CTX_set_cipher_data() function returns a pointer to the old +cipher data for the EVP_CIPHER_CTX. + +=head1 HISTORY + +The EVP_CIPHER_CTX_get_cipher_data() and EVP_CIPHER_CTX_set_cipher_data() +functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod b/openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod new file mode 100644 index 0000000..08e8290 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_CIPHER_meth_new.pod @@ -0,0 +1,253 @@ +=pod + +=head1 NAME + +EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free, +EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags, +EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init, +EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup, +EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params, +EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init, +EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup, +EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params, +EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len); + EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher); + void EVP_CIPHER_meth_free(EVP_CIPHER *cipher); + + int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len); + int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags); + int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size); + int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher, + int (*init) (EVP_CIPHER_CTX *ctx, + const unsigned char *key, + const unsigned char *iv, + int enc)); + int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher, + int (*do_cipher) (EVP_CIPHER_CTX *ctx, + unsigned char *out, + const unsigned char *in, + size_t inl)); + int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher, + int (*cleanup) (EVP_CIPHER_CTX *)); + int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher, + int (*set_asn1_parameters) (EVP_CIPHER_CTX *, + ASN1_TYPE *)); + int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher, + int (*get_asn1_parameters) (EVP_CIPHER_CTX *, + ASN1_TYPE *)); + int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher, + int (*ctrl) (EVP_CIPHER_CTX *, int type, + int arg, void *ptr)); + + int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, + const unsigned char *key, + const unsigned char *iv, + int enc); + int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, + unsigned char *out, + const unsigned char *in, + size_t inl); + int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *); + int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + ASN1_TYPE *); + int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + ASN1_TYPE *); + int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + int type, int arg, + void *ptr); + +=head1 DESCRIPTION + +The B<EVP_CIPHER> type is a structure for symmetric cipher method +implementation. + +EVP_CIPHER_meth_new() creates a new B<EVP_CIPHER> structure. + +EVP_CIPHER_meth_dup() creates a copy of B<cipher>. + +EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure. + +EVP_CIPHER_meth_iv_length() sets the length of the IV. +This is only needed when the implemented cipher mode requires it. + +EVP_CIPHER_meth_set_flags() sets the flags to describe optional +behaviours in the particular B<cipher>. +With the exception of cipher modes, of which only one may be present, +several flags can be or'd together. +The available flags are: + +=over 4 + +=item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE, +EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, +EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE, +EVP_CIPH_OCB_MODE + +The cipher mode. + +=item EVP_CIPH_VARIABLE_LENGTH + +This cipher is of variable length. + +=item EVP_CIPH_CUSTOM_IV + +Storing and initialising the IV is left entirely to the +implementation. + +=item EVP_CIPH_ALWAYS_CALL_INIT + +Set this if the implementation's init() function should be called even +if B<key> is B<NULL>. + +=item EVP_CIPH_CTRL_INIT + +Set this to have the implementation's ctrl() function called with +command code B<EVP_CTRL_INIT> early in its setup. + +=item EVP_CIPH_CUSTOM_KEY_LENGTH + +Checking and setting the key length after creating the B<EVP_CIPHER> +is left to the implementation. +Whenever someone uses EVP_CIPHER_CTX_set_key_length() on a +B<EVP_CIPHER> with this flag set, the implementation's ctrl() function +will be called with the control code B<EVP_CTRL_SET_KEY_LENGTH> and +the key length in B<arg>. + +=item EVP_CIPH_NO_PADDING + +Don't use standard block padding. + +=item EVP_CIPH_RAND_KEY + +Making a key with random content is left to the implementation. +This is done by calling the implementation's ctrl() function with the +control code B<EVP_CTRL_RAND_KEY> and the pointer to the key memory +storage in B<ptr>. + +=item EVP_CIPH_CUSTOM_COPY + +Set this to have the implementation's ctrl() function called with +command code B<EVP_CTRL_COPY> at the end of EVP_CIPHER_CTX_copy(). +The intended use is for further things to deal with after the +implementation specific data block has been copied. +The destination B<EVP_CIPHER_CTX> is passed to the control with the +B<ptr> parameter. +The implementation specific data block is reached with +EVP_CIPHER_CTX_get_cipher_data(). + +=item EVP_CIPH_FLAG_DEFAULT_ASN1 + +Use the default EVP routines to pass IV to and from ASN.1. + +=item EVP_CIPH_FLAG_LENGTH_BITS + +Signals that the length of the input buffer for encryption / +decryption is to be understood as the number of bits bits instead of +bytes for this implementation. +This is only useful for CFB1 ciphers. + +=begin comment +The FIPS flags seem to be unused, so I'm hiding them until I get an +explanation or they get removed. /RL + +=item EVP_CIPH_FLAG_FIPS + +=item EVP_CIPH_FLAG_NON_FIPS_ALLOW + +=end comment + +=item EVP_CIPH_FLAG_CUSTOM_CIPHER + +This indicates that the implementation takes care of everything, +including padding, buffering and finalization. +The EVP routines will simply give them control and do nothing more. + +=item EVP_CIPH_FLAG_AEAD_CIPHER + +This indicates that this is an AEAD cipher implementation. + +=item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK + +Allow interleaving of crypto blocks, a particular optimization only applicable +to certain TLS ciphers. + +=back + +EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's +implementation context so that it can be automatically allocated. + +EVP_CIPHER_meth_set_init() sets the cipher init function for +B<cipher>. +The cipher init function is called by EVP_CipherInit(), +EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(), +EVP_DecryptInit(), EVP_DecryptInit_ex(). + +EVP_CIPHER_meth_set_do_cipher() sets the cipher function for +B<cipher>. +The cipher function is called by EVP_CipherUpdate(), +EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(), +EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and +EVP_DecryptFinal_ex(). + +EVP_CIPHER_meth_set_cleanup() sets the function for B<cipher> to do +extra cleanup before the method's private data structure is cleaned +out and freed. +Note that the cleanup function is passed a B<EVP_CIPHER_CTX *>, the +private data structure is then available with +EVP_CIPHER_CTX_get_cipher_data(). +This cleanup function is called by EVP_CIPHER_CTX_reset() and +EVP_CIPHER_CTX_free(). + +EVP_CIPHER_meth_set_set_asn1_params() sets the function for B<cipher> +to set the AlgorithmIdentifier "parameter" based on the passed cipher. +This function is called by EVP_CIPHER_param_to_asn1(). +EVP_CIPHER_meth_set_get_asn1_params() sets the function for B<cipher> +that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier +"parameter". +Both these functions are needed when there is a need for custom data +(more or other than the cipher IV). +They are called by EVP_CIPHER_param_to_asn1() and +EVP_CIPHER_asn1_to_param() respectively if defined. + +EVP_CIPHER_meth_set_ctrl() sets the control function for B<cipher>. + +EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_do_cipher(), +EVP_CIPHER_meth_get_cleanup(), EVP_CIPHER_meth_get_set_asn1_params(), +EVP_CIPHER_meth_get_get_asn1_params() and EVP_CIPHER_meth_get_ctrl() +are all used to retrieve the method data given with the +EVP_CIPHER_meth_set_*() functions above. + +=head1 RETURN VALUES + +EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a +newly created B<EVP_CIPHER>, or NULL on failure. +All EVP_CIPHER_meth_set_*() functions return 1. +All EVP_CIPHER_meth_get_*() functions return pointers to their +respective B<cipher> function. + +=head1 SEE ALSO + +L<EVP_EncryptInit> + +=head1 HISTORY + +The B<EVP_CIPHER> structure was openly available in OpenSSL before version +1.1.0. +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_DigestInit.pod b/openssl-1.1.0h/doc/crypto/EVP_DigestInit.pod new file mode 100644 index 0000000..bb7ef7a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_DigestInit.pod @@ -0,0 +1,259 @@ +=pod + +=head1 NAME + +EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex, +EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex, +EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type, +EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, +EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha1, +EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_mdc2, +EVP_ripemd160, EVP_blake2b512, EVP_blake2s256, EVP_get_digestbyname, +EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_MD_CTX *EVP_MD_CTX_new(void); + int EVP_MD_CTX_reset(EVP_MD_CTX *ctx); + void EVP_MD_CTX_free(EVP_MD_CTX *ctx); + + int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); + int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); + int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, + unsigned int *s); + + 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_type(const EVP_MD *md); + int EVP_MD_pkey_type(const EVP_MD *md); + int EVP_MD_size(const EVP_MD *md); + int EVP_MD_block_size(const EVP_MD *md); + + const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); + int EVP_MD_CTX_size(const EVP_MD *ctx); + int EVP_MD_CTX_block_size(const EVP_MD *ctx); + int EVP_MD_CTX_type(const EVP_MD *ctx); + + const EVP_MD *EVP_md_null(void); + const EVP_MD *EVP_md2(void); + const EVP_MD *EVP_md5(void); + const EVP_MD *EVP_sha1(void); + const EVP_MD *EVP_mdc2(void); + const EVP_MD *EVP_ripemd160(void); + const EVP_MD *EVP_blake2b512(void); + const EVP_MD *EVP_blake2s256(void); + + const EVP_MD *EVP_sha224(void); + const EVP_MD *EVP_sha256(void); + const EVP_MD *EVP_sha384(void); + const EVP_MD *EVP_sha512(void); + + const EVP_MD *EVP_get_digestbyname(const char *name); + const EVP_MD *EVP_get_digestbynid(int type); + const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); + +=head1 DESCRIPTION + +The EVP digest routines are a high level interface to message digests, +and should be used instead of the cipher-specific functions. + +EVP_MD_CTX_new() allocates, initializes and returns a digest context. + +EVP_MD_CTX_reset() resets the digest context B<ctx>. This can be used +to reuse an already existing context. + +EVP_MD_CTX_free() cleans up digest context B<ctx> and frees up the +space allocated to it. + +EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest +B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this +function. B<type> will typically be supplied by a function such as EVP_sha1(). +If B<impl> is NULL then the default implementation of digest B<type> is used. + +EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the +digest context B<ctx>. This function can be called several times on the +same B<ctx> to hash additional data. + +EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places +it in B<md>. If the B<s> parameter is not NULL then the number of +bytes of data written (i.e. the length of the digest) will be written +to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. +After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() +can be made, but EVP_DigestInit_ex() can be called to initialize a new +digest operation. + +EVP_MD_CTX_copy_ex() can be used to copy the message digest state from +B<in> to B<out>. This is useful if large amounts of data are to be +hashed which only differ in the last few bytes. B<out> must be initialized +before calling this function. + +EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except +the passed context B<ctx> does not have to be initialized, and it always +uses the default digest implementation. + +EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest +context B<ctx> is automatically cleaned up. + +EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination +B<out> does not have to be initialized. + +EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest +when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the +hash. + +EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the +message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. + +EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER +representing the given message digest when passed an B<EVP_MD> structure. +For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is +normally used when setting ASN1 OIDs. + +EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed +B<EVP_MD_CTX>. + +EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated +with this digest. For example EVP_sha1() is associated with RSA so this will +return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms +are no longer linked this function is only retained for compatibility +reasons. + +EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(), +EVP_sha384(), EVP_sha512(), EVP_mdc2(), EVP_ripemd160(), EVP_blake2b512(), and +EVP_blake2s256() return B<EVP_MD> structures for the MD2, MD5, SHA1, SHA224, +SHA256, SHA384, SHA512, MDC2, RIPEMD160, BLAKE2b-512, and BLAKE2s-256 digest +algorithms respectively. + +EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it +returns is of zero length. + +EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() +return an B<EVP_MD> structure when passed a digest name, a digest NID or +an ASN1_OBJECT structure respectively. + +=head1 RETURN VALUES + +EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for +success and 0 for failure. + +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() and +EVP_MD_CTX_block_size() return the digest or block size in bytes. + +EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), +EVP_mdc2(), EVP_ripemd160(), EVP_blake2b512(), and EVP_blake2s256() return +pointers to the corresponding EVP_MD structures. + +EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() +return either an B<EVP_MD> structure or NULL if an error occurs. + +=head1 NOTES + +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. +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 +obsolete but are retained to maintain compatibility with existing code. New +applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and +EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context +instead of initializing and cleaning it up on each call and allow non default +implementations of digests to be specified. + +If digest contexts are not cleaned up after use +memory leaks will occur. + +EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(), +EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as +macros. + + +=head1 EXAMPLE + +This example digests the data "Test Message\n" and "Hello World\n", using the +digest name passed on the command line. + + #include <stdio.h> + #include <openssl/evp.h> + + main(int argc, char *argv[]) + { + EVP_MD_CTX *mdctx; + const EVP_MD *md; + char mess1[] = "Test Message\n"; + char mess2[] = "Hello World\n"; + unsigned char md_value[EVP_MAX_MD_SIZE]; + int md_len, i; + + if(!argv[1]) { + printf("Usage: mdtest digestname\n"); + exit(1); + } + + md = EVP_get_digestbyname(argv[1]); + + if(!md) { + printf("Unknown message digest %s\n", argv[1]); + exit(1); + } + + mdctx = EVP_MD_CTX_new(); + EVP_DigestInit_ex(mdctx, md, NULL); + EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); + EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); + EVP_DigestFinal_ex(mdctx, md_value, &md_len); + EVP_MD_CTX_free(mdctx); + + printf("Digest is: "); + for (i = 0; i < md_len; i++) + printf("%02x", md_value[i]); + printf("\n"); + + exit(0); + } + +=head1 SEE ALSO + +L<dgst(1)>, +L<evp(7)> + +=head1 HISTORY + +B<EVP_MD_CTX> became opaque in OpenSSL 1.1. Consequently, stack +allocated B<EVP_MD_CTX>s are no longer supported. + +EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to +EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1. + +The link between digests and signing algorithms was fixed in OpenSSL 1.0 and +later, so now EVP_sha1() can be used with RSA and DSA. The legacy EVP_dss1() +was removed in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_DigestSignInit.pod b/openssl-1.1.0h/doc/crypto/EVP_DigestSignInit.pod new file mode 100644 index 0000000..7ec06b7 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_DigestSignInit.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, + const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); + int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); + int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital signatures. + +EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from +ENGINE B<impl> and private key B<pkey>. B<ctx> must be created with +EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the +EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can +be used to set alternative signing options. + +EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the +signature context B<ctx>. This function can be called several times on the +same B<ctx> to include additional data. This function is currently implemented +using a macro. + +EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>. +If B<sig> is B<NULL> then the maximum size of the output buffer is written to +the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the +B<siglen> parameter should contain the length of the B<sig> buffer, if the +call is successful the signature is written to B<sig> and the amount of data +written to B<siglen>. + +=head1 RETURN VALUES + +EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return +1 for success and 0 or a negative value for failure. In particular a return +value of -2 indicates the operation is not supported by the public key +algorithm. + +The error codes can be obtained from L<ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +In previous versions of OpenSSL there was a link between message digest types +and public key algorithms. This meant that "clone" digests such as EVP_dss1() +needed to be used to sign using SHA1 and DSA. This is no longer necessary and +the use of clone digest is now discouraged. + +For some key types and parameters the random number generator must be seeded +or the operation will fail. + +The call to EVP_DigestSignFinal() internally finalizes a copy of the digest +context. This means that calls to EVP_DigestSignUpdate() and +EVP_DigestSignFinal() can be called later to digest and sign additional data. + +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak +will occur. + +The use of EVP_PKEY_size() with these functions is discouraged because some +signature operations may have a signature length which depends on the +parameters set. As a result EVP_PKEY_size() would have to return a value +which indicates the maximum possible signature for any set of parameters. + +=head1 SEE ALSO + +L<EVP_DigestVerifyInit(3)>, +L<EVP_DigestInit(3)>, +L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, +L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, +L<SHA1(3)>, L<dgst(1)> + +=head1 HISTORY + +EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() +were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_DigestVerifyInit.pod b/openssl-1.1.0h/doc/crypto/EVP_DigestVerifyInit.pod new file mode 100644 index 0000000..ce59422 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_DigestVerifyInit.pod @@ -0,0 +1,91 @@ +=pod + +=head1 NAME + +EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signature verification functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, + const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); + int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); + int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig, size_t siglen); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital signatures. + +EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest +B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be created +with EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the +EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this +can be used to set alternative verification options. + +EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the +verification context B<ctx>. This function can be called several times on the +same B<ctx> to include additional data. This function is currently implemented +using a macro. + +EVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in +B<sig> of length B<siglen>. + +=head1 RETURN VALUES + +EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 +for failure. + +EVP_DigestVerifyFinal() returns 1 for success; any other value indicates +failure. A return value of zero indicates that the signature did not verify +successfully (that is, tbs did not match the original data or the signature had +an invalid form), while other values indicate a more serious error (and +sometimes also indicate an invalid signature form). + +The error codes can be obtained from L<ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +In previous versions of OpenSSL there was a link between message digest types +and public key algorithms. This meant that "clone" digests such as EVP_dss1() +needed to be used to sign using SHA1 and DSA. This is no longer necessary and +the use of clone digest is now discouraged. + +For some key types and parameters the random number generator must be seeded +or the operation will fail. + +The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest +context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can +be called later to digest and verify additional data. + +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak +will occur. + +=head1 SEE ALSO + +L<EVP_DigestSignInit(3)>, +L<EVP_DigestInit(3)>, +L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, +L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, +L<SHA1(3)>, L<dgst(1)> + +=head1 HISTORY + +EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() +were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_EncodeInit.pod b/openssl-1.1.0h/doc/crypto/EVP_EncodeInit.pod new file mode 100644 index 0000000..d919b14 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_EncodeInit.pod @@ -0,0 +1,162 @@ +=pod + +=head1 NAME + +EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy, +EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, +EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, +EVP_DecodeBlock - EVP base 64 encode/decode routines + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void); + void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx); + int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx); + int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx); + void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); + int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, + const unsigned char *in, int inl); + void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); + int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n); + + void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); + int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, + const unsigned char *in, int inl); + int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned + char *out, int *outl); + int EVP_DecodeBlock(unsigned char *t, const unsigned char *f, int n); + +=head1 DESCRIPTION + +The EVP encode routines provide a high level interface to base 64 encoding and +decoding. Base 64 encoding converts binary data into a printable form that uses +the characters A-Z, a-z, 0-9, "+" and "/" to represent the data. For every 3 +bytes of binary data provided 4 bytes of base 64 encoded data will be produced +plus some occasional newlines (see below). If the input data length is not a +multiple of 3 then the output data will be padded at the end using the "=" +character. + +EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for +the encode/decode functions. + +EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the +space allocated to it. + +Encoding of binary data is performed in blocks of 48 input bytes (or less for +the final block). For each 48 byte input block encoded 64 bytes of base 64 data +is output plus an additional newline character (i.e. 65 bytes in total). The +final block (which may be less than 48 bytes) will output 4 bytes for every 3 +bytes of input. If the data length is not divisible by 3 then a full 4 bytes is +still output for the final 1 or 2 bytes of input. Similarly a newline character +will also be output. + +EVP_EncodeInit() initialises B<ctx> for the start of a new encoding operation. + +EVP_EncodeUpdate() encode B<inl> bytes of data found in the buffer pointed to by +B<in>. The output is stored in the buffer B<out> and the number of bytes output +is stored in B<*outl>. It is the caller's responsibility to ensure that the +buffer at B<out> is sufficiently large to accommodate the output data. Only full +blocks of data (48 bytes) will be immediately processed and output by this +function. Any remainder is held in the B<ctx> object and will be processed by a +subsequent call to EVP_EncodeUpdate() or EVP_EncodeFinal(). To calculate the +required size of the output buffer add together the value of B<inl> with the +amount of unprocessed data held in B<ctx> and divide the result by 48 (ignore +any remainder). This gives the number of blocks of data that will be processed. +Ensure the output buffer contains 65 bytes of storage for each block, plus an +additional byte for a NUL terminator. EVP_EncodeUpdate() may be called +repeatedly to process large amounts of input data. In the event of an error +EVP_EncodeUpdate() will set B<*outl> to 0 and return 0. On success 1 will be +returned. + +EVP_EncodeFinal() must be called at the end of an encoding operation. It will +process any partial block of data remaining in the B<ctx> object. The output +data will be stored in B<out> and the length of the data written will be stored +in B<*outl>. It is the caller's responsibility to ensure that B<out> is +sufficiently large to accommodate the output data which will never be more than +65 bytes plus an additional NUL terminator (i.e. 66 bytes in total). + +EVP_ENCODE_CTX_copy() can be used to copy a context B<sctx> to a context +B<dctx>. B<dctx> must be initialized before calling this function. + +EVP_ENCODE_CTX_num() will return the number of as yet unprocessed bytes still to +be encoded or decoded that are pending in the B<ctx> object. + +EVP_EncodeBlock() encodes a full block of input data in B<f> and of length +B<dlen> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of +output data will be produced. If B<dlen> is not divisible by 3 then the block is +encoded as a final block of data and the output is padded such that it is always +divisible by 4. Additionally a NUL terminator character will be added. For +example if 16 bytes of input data is provided then 24 bytes of encoded data is +created plus 1 byte for a NUL terminator (i.e. 25 bytes in total). The length of +the data generated I<without> the NUL terminator is returned from the function. + +EVP_DecodeInit() initialises B<ctx> for the start of a new decoding operation. + +EVP_DecodeUpdate() decodes B<inl> characters of data found in the buffer pointed +to by B<in>. The output is stored in the buffer B<out> and the number of bytes +output is stored in B<*outl>. It is the caller's responsibility to ensure that +the buffer at B<out> is sufficiently large to accommodate the output data. This +function will attempt to decode as much data as possible in 4 byte chunks. Any +whitespace, newline or carriage return characters are ignored. Any partial chunk +of unprocessed data (1, 2 or 3 bytes) that remains at the end will be held in +the B<ctx> object and processed by a subsequent call to EVP_DecodeUpdate(). If +any illegal base 64 characters are encountered or if the base 64 padding +character "=" is encountered in the middle of the data then the function returns +-1 to indicate an error. A return value of 0 or 1 indicates successful +processing of the data. A return value of 0 additionally indicates that the last +input data characters processed included the base 64 padding character "=" and +therefore no more non-padding character data is expected to be processed. For +every 4 valid base 64 bytes processed (ignoring whitespace, carriage returns and +line feeds), 3 bytes of binary output data will be produced (or less at the end +of the data where the padding character "=" has been used). + +EVP_DecodeFinal() must be called at the end of a decoding operation. If there +is any unprocessed data still in B<ctx> then the input data must not have been +a multiple of 4 and therefore an error has occurred. The function will return -1 +in this case. Otherwise the function returns 1 on success. + +EVP_DecodeBlock() will decode the block of B<n> characters of base 64 data +contained in B<f> and store the result in B<t>. Any leading whitespace will be +trimmed as will any trailing whitespace, newlines, carriage returns or EOF +characters. After such trimming the length of the data in B<f> must be divisible +by 4. For every 4 input bytes exactly 3 output bytes will be produced. The +output will be padded with 0 bits if necessary to ensure that the output is +always 3 bytes for every 4 input bytes. This function will return the length of +the data decoded or -1 on error. + +=head1 RETURN VALUES + +EVP_ENCODE_CTX_new() returns a pointer to the newly allocated EVP_ENCODE_CTX +object or NULL on error. + +EVP_ENCODE_CTX_num() returns the number of bytes pending encoding or decoding in +B<ctx>. + +EVP_EncodeUpdate() returns 0 on error or 1 on success. + +EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL +terminator. + +EVP_DecodeUpdate() returns -1 on error and 0 or 1 on success. If 0 is returned +then no more non-padding base 64 characters are expected. + +EVP_DecodeFinal() returns -1 on error or 1 on success. + +EVP_DecodeBlock() returns the length of the data decoded or -1 on error. + +=head1 SEE ALSO + +L<evp(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_EncryptInit.pod b/openssl-1.1.0h/doc/crypto/EVP_EncryptInit.pod new file mode 100644 index 0000000..d1af772 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_EncryptInit.pod @@ -0,0 +1,661 @@ +=pod + +=head1 NAME + +EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free, +EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex, +EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex, +EVP_CipherInit_ex, EVP_CipherUpdate, EVP_CipherFinal_ex, +EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit, +EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, +EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname, +EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, +EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, +EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, +EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, +EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data, +EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags, +EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, +EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb, +EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb, +EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb, +EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_rc4_hmac_md5, +EVP_idea_cbc, EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_rc2_cbc, +EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, +EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, +EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc, +EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, +EVP_aes_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb, +EVP_aes_192_cbc, EVP_aes_192_ecb, EVP_aes_192_cfb, EVP_aes_192_ofb, +EVP_aes_256_cbc, EVP_aes_256_ecb, EVP_aes_256_cfb, EVP_aes_256_ofb, +EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, +EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm, +EVP_aes_128_cbc_hmac_sha1, EVP_aes_256_cbc_hmac_sha1, +EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256, +EVP_chacha20, EVP_chacha20_poly1305 - EVP cipher routines + +=head1 SYNOPSIS + +=for comment generic + + #include <openssl/evp.h> + + EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); + int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); + void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); + + int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + ENGINE *impl, const unsigned char *key, const unsigned char *iv); + int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, const unsigned char *in, int inl); + int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + + int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + ENGINE *impl, const unsigned char *key, const unsigned char *iv); + int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, const unsigned char *in, int inl); + int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, + int *outl); + + int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc); + int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, const unsigned char *in, int inl); + int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, + int *outl); + + int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + const unsigned char *key, const unsigned char *iv); + int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + + int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + const unsigned char *key, const unsigned char *iv); + int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, + int *outl); + + int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + const unsigned char *key, const unsigned char *iv, int enc); + int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, + int *outl); + + int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); + int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); + int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); + + const EVP_CIPHER *EVP_get_cipherbyname(const char *name); + const EVP_CIPHER *EVP_get_cipherbynid(int nid); + const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); + + int EVP_CIPHER_nid(const EVP_CIPHER *e); + int EVP_CIPHER_block_size(const EVP_CIPHER *e); + int EVP_CIPHER_key_length(const EVP_CIPHER *e) + int EVP_CIPHER_key_length(const EVP_CIPHER *e); + int EVP_CIPHER_iv_length(const EVP_CIPHER *e); + unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e); + unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e); + int EVP_CIPHER_type(const EVP_CIPHER *ctx); + + const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx); + void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); + void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data); + int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx); + + int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); + int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); + +=head1 DESCRIPTION + +The EVP cipher routines are a high level interface to certain +symmetric ciphers. + +EVP_CIPHER_CTX_new() creates a cipher context. + +EVP_CIPHER_CTX_free() clears all information from a cipher context +and free up any allocated memory associate with it, including B<ctx> +itself. This function should be called after all operations using a +cipher are complete so sensitive information does not remain in +memory. + +EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption +with cipher B<type> from ENGINE B<impl>. B<ctx> must be created +before calling this function. B<type> is normally supplied +by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the +default implementation is used. B<key> is the symmetric key to use +and B<iv> is the IV to use (if necessary), the actual number of bytes +used for the key and IV depends on the cipher. It is possible to set +all parameters to NULL except B<type> in an initial call and supply +the remaining parameters in subsequent calls, all of which have B<type> +set to NULL. This is done when the default cipher parameters are not +appropriate. + +EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and +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<out> should contain sufficient +room. The actual number of bytes written is placed in B<outl>. It also +checks if B<in> and B<out> are partially overlapping, and if they are +0 is returned to indicate failure. + +If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts +the "final" data, that is any data that remains in a partial block. +It uses standard block padding (aka PKCS padding) as described in +the NOTES section, below. The encrypted +final data is written to B<out> which should have sufficient space for +one cipher block. The number of bytes written is placed in B<outl>. After +this function is called the encryption operation is finished and no further +calls to EVP_EncryptUpdate() should be made. + +If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more +data and it will return an error if any data remains in a partial block: +that is if the total data length is not a multiple of the block size. + +EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the +corresponding decryption operations. EVP_DecryptFinal() will return an +error code if padding is enabled and the final block is not correctly +formatted. The parameters and restrictions are identical to the encryption +operations except that if padding is enabled the decrypted data buffer B<out> +passed to EVP_DecryptUpdate() should have sufficient room for +(B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in +which case B<inl> bytes is sufficient. + +EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are +functions that can be used for decryption or encryption. The operation +performed depends on the value of the B<enc> parameter. It should be set +to 1 for encryption, 0 for decryption and -1 to leave the value unchanged +(the actual value of 'enc' being supplied in a previous call). + +EVP_CIPHER_CTX_reset() clears all information from a cipher context +and free up any allocated memory associate with it, except the B<ctx> +itself. This function should be called anytime B<ctx> is to be reused +for another EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal() +series of calls. + +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> parameter does not need to be +initialized and they always use the default cipher implementation. + +EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are +identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and +EVP_CipherFinal_ex(). In previous releases they also cleaned up +the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean() +must be called to free any context resources. + +EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() +return an EVP_CIPHER structure when passed a cipher name, a NID or an +ASN1_OBJECT structure. + +EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when +passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID +value is an internal value which may not have a corresponding OBJECT +IDENTIFIER. + +EVP_CIPHER_CTX_set_padding() enables or disables padding. This +function should be called after the context is set up for encryption +or decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or +EVP_CipherInit_ex(). By default encryption operations are padded using +standard block padding and the padding is checked and removed when +decrypting. If the B<pad> parameter is zero then no padding is +performed, the total amount of data encrypted or decrypted must then +be a multiple of the block size or an error will occur. + +EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key +length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> +structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length +for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a +given cipher, the value of EVP_CIPHER_CTX_key_length() may be different +for variable key length ciphers. + +EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx. +If the cipher is a fixed length cipher then attempting to set the key +length to any value other than the fixed value is an error. + +EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV +length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>. +It will return zero if the cipher does not use an IV. The constant +B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers. + +EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block +size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> +structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the maximum block +length for all ciphers. + +EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed +cipher or context. This "type" is the actual NID of the cipher OBJECT +IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and +128 bit RC2 have the same NID. If the cipher does not have an object +identifier or does not have ASN1 support this function will return +B<NID_undef>. + +EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed +an B<EVP_CIPHER_CTX> structure. + +EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode: +EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or +EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then +EVP_CIPH_STREAM_CIPHER is returned. + +EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based +on the passed cipher. This will typically include any parameters and an +IV. The cipher IV (if any) must be set when this call is made. This call +should be made before the cipher is actually "used" (before any +EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function +may fail if the cipher does not have any ASN1 support. + +EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 +AlgorithmIdentifier "parameter". The precise effect depends on the cipher +In the case of RC2, for example, it will set the IV and effective key length. +This function should be called after the base cipher type is set but before +the key is set. For example EVP_CipherInit() will be called with the IV and +key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally +EVP_CipherInit() again with all parameters except the key set to NULL. It is +possible for this function to fail if the cipher does not have any ASN1 support +or the parameters cannot be set (for example the RC2 effective key length +is not supported. + +EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined +and set. + +=head1 RETURN VALUES + +EVP_CIPHER_CTX_new() returns a pointer to a newly created +B<EVP_CIPHER_CTX> for success and B<NULL> for failure. + +EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() +return 1 for success and 0 for failure. + +EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for failure. +EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success. + +EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure. +EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success. + +EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure. + +EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() +return an B<EVP_CIPHER> structure or NULL on error. + +EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. + +EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block +size. + +EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key +length. + +EVP_CIPHER_CTX_set_padding() always returns 1. + +EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV +length or zero if the cipher does not use an IV. + +EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's +OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. + +EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. + +EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater +than zero for success and zero or a negative number. + +=head1 CIPHER LISTING + +All algorithms have a fixed key length unless otherwise stated. + +=over 4 + +=item EVP_enc_null() + +Null cipher: does nothing. + +=item EVP_aes_128_cbc(), EVP_aes_128_ecb(), EVP_aes_128_cfb(), EVP_aes_128_ofb() + +AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_aes_192_cbc(), EVP_aes_192_ecb(), EVP_aes_192_cfb(), EVP_aes_192_ofb() + +AES with a 192-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_aes_256_cbc(), EVP_aes_256_ecb(), EVP_aes_256_cfb(), EVP_aes_256_ofb() + +AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_ofb() + +DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_ede_cbc(), EVP_des_ede(), EVP_des_ede_ofb(), EVP_des_ede_cfb() + +Two key triple DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_ede3_cbc(), EVP_des_ede3(), EVP_des_ede3_ofb(), EVP_des_ede3_cfb() + +Three key triple DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_desx_cbc() + +DESX algorithm in CBC mode. + +=item EVP_rc4() + +RC4 stream cipher. This is a variable key length cipher with default key length 128 bits. + +=item EVP_rc4_40() + +RC4 stream cipher with 40 bit key length. +This is obsolete and new code should use EVP_rc4() +and the EVP_CIPHER_CTX_set_key_length() function. + +=item EVP_idea_cbc() EVP_idea_ecb(), EVP_idea_cfb(), EVP_idea_ofb() + +IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_rc2_cbc(), EVP_rc2_ecb(), EVP_rc2_cfb(), EVP_rc2_ofb() + +RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key +length cipher with an additional parameter called "effective key bits" or "effective key length". +By default both are set to 128 bits. + +=item EVP_rc2_40_cbc(), EVP_rc2_64_cbc() + +RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits. +These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and +EVP_CIPHER_CTX_ctrl() to set the key length and effective key length. + +=item EVP_bf_cbc(), EVP_bf_ecb(), EVP_bf_cfb(), EVP_bf_ofb() + +Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key +length cipher. + +=item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_ofb() + +CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key +length cipher. + +=item EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_ofb() + +RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length +cipher with an additional "number of rounds" parameter. By default the key length is set to 128 +bits and 12 rounds. + +=item EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm() + +AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively. +These ciphers require additional control operations to function correctly: see +the L</GCM and OCB Modes> section below for details. + +=item EVP_aes_128_ocb(void), EVP_aes_192_ocb(void), EVP_aes_256_ocb(void) + +Offset Codebook Mode (OCB) for 128, 192 and 256 bit keys respectively. +These ciphers require additional control operations to function correctly: see +the L</GCM and OCB Modes> section below for details. + +=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm() + +AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively. +These ciphers require additional control operations to function correctly: see +CCM mode section below for details. + +=item EVP_chacha20() + +The ChaCha20 stream cipher. The key length is 256 bits, the IV is 96 bits long. + +=item EVP_chacha20_poly1305() + +Authenticated encryption with ChaCha20-Poly1305. Like EVP_chacha20() the key is +256 bits and the IV is 96 bits. This supports additional authenticated +data (AAD) and produces a 128 bit authentication tag. See the +L</GCM and OCB Modes> section for more information. + +=back + +=head1 GCM and OCB Modes + +For GCM and OCB mode ciphers the behaviour of the EVP interface is subtly +altered and several additional ctrl operations are supported. + +To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(), +EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output +parameter B<out> set to B<NULL>. + +When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() +indicates if the operation was successful. If it does not indicate success +the authentication operation has failed and any output data B<MUST NOT> +be used as it is corrupted. + +The following ctrls are supported in both GCM and OCB modes: + + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL); + +Sets the IV length: this call can only be made before specifying an IV. If +not called a default IV length is used. For GCM AES and OCB AES the default is +12 (i.e. 96 bits). For OCB mode the maximum is 15. + + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag); + +Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>. +This call can only be made when encrypting data and B<after> all data has been +processed (e.g. after an EVP_EncryptFinal() call). For OCB mode the taglen must +either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN. + + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag); + +Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal +when decrypting data. For OCB mode the taglen must either be 16 or the value +previously set via EVP_CTRL_AEAD_SET_TAG. + +In OCB mode calling this with B<tag> set to NULL sets the tag length. The tag +length can only be set before specifying an IV. If not called a default tag +length is used. For OCB AES the default is 16 (i.e. 128 bits). This is also the +maximum tag length for OCB. + +=head1 CCM Mode + +The behaviour of CCM mode ciphers is similar to GCM mode but with a few +additional requirements and different ctrl values. + +Like GCM and OCB modes any additional authenticated data (AAD) is passed by calling +EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output +parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext +length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or +EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>) +set to B<NULL> and the length passed in the B<inl> parameter. + +The following ctrls are supported in CCM mode: + + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag); + +This call is made to set the expected B<CCM> tag value when decrypting or +the length of the tag (with the B<tag> parameter set to NULL) when encrypting. +The tag length is often referred to as B<M>. If not set a default value is +used (12 for AES). + + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL); + +Sets the CCM B<L> value. If not set a default is used (8 for AES). + + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL); + +Sets the CCM nonce (IV) length: this call can only be made before specifying +an nonce value. The nonce length is given by B<15 - L> so it is 7 by default +for AES. + +=head1 NOTES + +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. 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 +added so if the data is already a multiple of the block size B<n> will equal +the block size. For example if the block size is 8 and 11 bytes are to be +encrypted then 5 padding bytes of value 5 will be added. + +When decrypting the final block is checked to see if it has the correct form. + +Although the decryption operation can produce an error if padding is enabled, +it is not a strong test that the input data or key is correct. A random block +has better than 1 in 256 chance of being of the correct format and problems with +the input data earlier on will not produce a final decrypt error. + +If padding is disabled then the decryption operation will always succeed if +the total amount of data decrypted is a multiple of the block size. + +The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(), +EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for +compatibility with existing code. New code should use EVP_EncryptInit_ex(), +EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), +EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an +existing context without allocating and freeing it up on each call. + +EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros. + +=head1 BUGS + +For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is +a limitation of the current RC5 code rather than the EVP interface. + +EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with +default key lengths. If custom ciphers exceed these values the results are +unpredictable. This is because it has become standard practice to define a +generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes. + +The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested +for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. + +=head1 EXAMPLES + +Encrypt a string using IDEA: + + int do_crypt(char *outfile) + { + unsigned char outbuf[1024]; + int outlen, tmplen; + /* Bogus key and IV: we'd normally set these from + * another source. + */ + unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; + unsigned char iv[] = {1,2,3,4,5,6,7,8}; + char intext[] = "Some Crypto Text"; + EVP_CIPHER_CTX *ctx; + FILE *out; + + ctx = EVP_CIPHER_CTX_new(); + EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv); + + if(!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) + { + /* Error */ + return 0; + } + /* Buffer passed to EVP_EncryptFinal() must be after data just + * encrypted to avoid overwriting it. + */ + if(!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) + { + /* Error */ + return 0; + } + outlen += tmplen; + EVP_CIPHER_CTX_free(ctx); + /* Need binary mode for fopen because encrypted data is + * binary data. Also cannot use strlen() on it because + * it won't be null terminated and may contain embedded + * nulls. + */ + out = fopen(outfile, "wb"); + fwrite(outbuf, 1, outlen, out); + fclose(out); + return 1; + } + +The ciphertext from the above example can be decrypted using the B<openssl> +utility with the command line (shown on two lines for clarity): + + openssl idea -d <filename + -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 + +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 */ + 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[] = "0123456789abcdeF"; + unsigned char iv[] = "1234567887654321"; + + /* Don't set key or IV right away; we want to check lengths */ + ctx = EVP_CIPHER_CTX_new(); + 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(;;) + { + inlen = fread(inbuf, 1, 1024, in); + if (inlen <= 0) break; + if(!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) + { + /* Error */ + EVP_CIPHER_CTX_free(ctx); + return 0; + } + fwrite(outbuf, 1, outlen, out); + } + if(!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) + { + /* Error */ + EVP_CIPHER_CTX_free(ctx); + return 0; + } + fwrite(outbuf, 1, outlen, out); + + EVP_CIPHER_CTX_free(ctx); + return 1; + } + + +=head1 SEE ALSO + +L<evp(7)> + +=head1 HISTORY + +Support for OCB mode was added in OpenSSL 1.1.0 + +B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0. As a result, +EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup() +disappeared. EVP_CIPHER_CTX_init() remains as an alias for +EVP_CIPHER_CTX_reset(). + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_MD_meth_new.pod b/openssl-1.1.0h/doc/crypto/EVP_MD_meth_new.pod new file mode 100644 index 0000000..4dac672 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_MD_meth_new.pod @@ -0,0 +1,179 @@ +=pod + +=head1 NAME + +EVP_MD_meth_dup, +EVP_MD_meth_new, EVP_MD_meth_free, EVP_MD_meth_set_input_blocksize, +EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize, +EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update, +EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup, +EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize, +EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize, +EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update, +EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup, +EVP_MD_meth_get_ctrl +- Routines to build up EVP_MD methods + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type); + void EVP_MD_meth_free(EVP_MD *md); + EVP_MD *EVP_MD_meth_dup(const EVP_MD *md); + + int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize); + int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize); + int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize); + int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags); + int EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx)); + int EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx, + const void *data, + size_t count)); + int EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx, + unsigned char *md)); + int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to, + const EVP_MD_CTX *from)); + int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx)); + int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd, + int p1, void *p2)); + + int EVP_MD_meth_get_input_blocksize(const EVP_MD *md); + int EVP_MD_meth_get_result_size(const EVP_MD *md); + int EVP_MD_meth_get_app_datasize(const EVP_MD *md); + unsigned long EVP_MD_meth_get_flags(const EVP_MD *md); + int (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx); + int (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx, + const void *data, + size_t count); + int (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx, + unsigned char *md); + int (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to, + const EVP_MD_CTX *from); + int (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx); + int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd, + int p1, void *p2); + +=head1 DESCRIPTION + +The B<EVP_MD> type is a structure for digest method implementation. +It can also have associated public/private key signing and verifying +routines. + +EVP_MD_meth_new() creates a new B<EVP_MD> structure. + +EVP_MD_meth_dup() creates a copy of B<md>. + +EVP_MD_meth_free() destroys a B<EVP_MD> structure. + +EVP_MD_meth_set_input_blocksize() sets the internal input block size +for the method B<md> to B<blocksize> bytes. + +EVP_MD_meth_set_result_size() sets the size of the result that the +digest method in B<md> is expected to produce to B<resultsize> bytes. + +The digest method may have its own private data, which OpenSSL will +allocate for it. EVP_MD_meth_set_app_datasize() should be used to +set the size for it to B<datasize>. + +EVP_MD_meth_set_flags() sets the flags to describe optional +behaviours in the particular B<md>. Several flags can be or'd +together. The available flags are: + +=over 4 + +=item EVP_MD_FLAG_ONESHOT + +This digest method can only handles one block of input. + +=item EVP_MD_FLAG_DIGALGID_NULL + +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter set to NULL by default. Use this for PKCS#1. I<Note: if +combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.> + +=item EVP_MD_FLAG_DIGALGID_ABSENT + +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter be left absent by default. I<Note: if combined with +EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> + +=item EVP_MD_FLAG_DIGALGID_CUSTOM + +Custom DigestAlgorithmIdentifier handling via ctrl, with +B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with +EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> +Currently unused. + +=back + +EVP_MD_meth_set_init() sets the digest init function for B<md>. +The digest init function is called by EVP_DigestInit(), +EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit() +and EVP_VerifyInit_ex(). + +EVP_MD_meth_set_update() sets the digest update function for B<md>. +The digest update function is called by EVP_DigestUpdate(), +EVP_SignUpdate(). + +EVP_MD_meth_set_final() sets the digest final function for B<md>. +The digest final function is called by EVP_DigestFinal(), +EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal(). + +EVP_MD_meth_set_copy() sets the function for B<md> to do extra +computations after the method's private data structure has been copied +from one B<EVP_MD_CTX> to another. If all that's needed is to copy +the data, there is no need for this copy function. +Note that the copy function is passed two B<EVP_MD_CTX *>, the private +data structure is then available with EVP_MD_CTX_md_data(). +This copy function is called by EVP_MD_CTX_copy() and +EVP_MD_CTX_copy_ex(). + +EVP_MD_meth_set_cleanup() sets the function for B<md> to do extra +cleanup before the method's private data structure is cleaned out and +freed. +Note that the cleanup function is passed a B<EVP_MD_CTX *>, the +private data structure is then available with EVP_MD_CTX_md_data(). +This cleanup function is called by EVP_MD_CTX_reset() and +EVP_MD_CTX_free(). + +EVP_MD_meth_set_ctrl() sets the control function for B<md>. + +EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(), +EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(), +EVP_MD_meth_get_init(), EVP_MD_meth_get_update(), +EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(), +EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used +to retrieve the method data given with the EVP_MD_meth_set_*() +functions above. + +=head1 RETURN VALUES + +EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly +created B<EVP_MD>, or NULL on failure. +All EVP_MD_meth_set_*() functions return 1. +EVP_MD_get_input_blocksize(), EVP_MD_meth_get_result_size(), +EVP_MD_meth_get_app_datasize() and EVP_MD_meth_get_flags() return the +indicated sizes or flags. +All other EVP_CIPHER_meth_get_*() functions return pointers to their +respective B<md> function. + +=head1 SEE ALSO + +L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)> + +=head1 HISTORY + +The B<EVP_MD> structure was openly available in OpenSSL before version +1.1.0. The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_OpenInit.pod b/openssl-1.1.0h/doc/crypto/EVP_OpenInit.pod new file mode 100644 index 0000000..ff84490 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_OpenInit.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_OpenInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *ek, + int ekl, unsigned char *iv, EVP_PKEY *priv); + int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + +=head1 DESCRIPTION + +The EVP envelope routines are a high level interface to envelope +decryption. They decrypt a public key encrypted symmetric key and +then decrypt data using it. + +EVP_OpenInit() initializes a cipher context B<ctx> for decryption +with cipher B<type>. It decrypts the encrypted symmetric key of length +B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>. +The IV is supplied in the B<iv> parameter. + +EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties +as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as +documented on the L<EVP_EncryptInit(3)> manual +page. + +=head1 NOTES + +It is possible to call EVP_OpenInit() twice in the same way as +EVP_DecryptInit(). The first call should have B<priv> set to NULL +and (after setting any cipher parameters) it should be called again +with B<type> set to NULL. + +If the cipher passed in the B<type> parameter is a variable length +cipher then the key length will be set to the value of the recovered +key length. If the cipher is a fixed length cipher then the recovered +key length must match the fixed cipher length. + +=head1 RETURN VALUES + +EVP_OpenInit() returns 0 on error or a non zero integer (actually the +recovered secret key size) if successful. + +EVP_OpenUpdate() returns 1 for success or 0 for failure. + +EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success. + +=head1 SEE ALSO + +L<evp(3)>, L<rand(3)>, +L<EVP_EncryptInit(3)>, +L<EVP_SealInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_ASN1_METHOD.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_ASN1_METHOD.pod new file mode 100644 index 0000000..0eece53 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_ASN1_METHOD.pod @@ -0,0 +1,358 @@ +=pod + +=head1 NAME + +EVP_PKEY_ASN1_METHOD, +EVP_PKEY_asn1_new, +EVP_PKEY_asn1_copy, +EVP_PKEY_asn1_free, +EVP_PKEY_asn1_add0, +EVP_PKEY_asn1_add_alias, +EVP_PKEY_asn1_set_public, +EVP_PKEY_asn1_set_private, +EVP_PKEY_asn1_set_param, +EVP_PKEY_asn1_set_free, +EVP_PKEY_asn1_set_ctrl, +EVP_PKEY_asn1_set_item, +EVP_PKEY_asn1_set_security_bits, +EVP_PKEY_get0_asn1 +- manipulating and registering EVP_PKEY_ASN1_METHOD structure + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD; + + EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags, + const char *pem_str, + const char *info); + void EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst, + const EVP_PKEY_ASN1_METHOD *src); + void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth); + int EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth); + int EVP_PKEY_asn1_add_alias(int to, int from); + + void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth, + int (*pub_decode) (EVP_PKEY *pk, + X509_PUBKEY *pub), + int (*pub_encode) (X509_PUBKEY *pub, + const EVP_PKEY *pk), + int (*pub_cmp) (const EVP_PKEY *a, + const EVP_PKEY *b), + int (*pub_print) (BIO *out, + const EVP_PKEY *pkey, + int indent, ASN1_PCTX *pctx), + int (*pkey_size) (const EVP_PKEY *pk), + int (*pkey_bits) (const EVP_PKEY *pk)); + void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth, + int (*priv_decode) (EVP_PKEY *pk, + const PKCS8_PRIV_KEY_INFO + *p8inf), + int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, + const EVP_PKEY *pk), + int (*priv_print) (BIO *out, + const EVP_PKEY *pkey, + int indent, + ASN1_PCTX *pctx)); + void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth, + int (*param_decode) (EVP_PKEY *pkey, + const unsigned char **pder, + int derlen), + int (*param_encode) (const EVP_PKEY *pkey, + unsigned char **pder), + int (*param_missing) (const EVP_PKEY *pk), + int (*param_copy) (EVP_PKEY *to, + const EVP_PKEY *from), + int (*param_cmp) (const EVP_PKEY *a, + const EVP_PKEY *b), + int (*param_print) (BIO *out, + const EVP_PKEY *pkey, + int indent, + ASN1_PCTX *pctx)); + + void EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth, + void (*pkey_free) (EVP_PKEY *pkey)); + void EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth, + int (*pkey_ctrl) (EVP_PKEY *pkey, int op, + long arg1, void *arg2)); + void EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth, + int (*item_verify) (EVP_MD_CTX *ctx, + const ASN1_ITEM *it, + void *asn, + X509_ALGOR *a, + ASN1_BIT_STRING *sig, + EVP_PKEY *pkey), + int (*item_sign) (EVP_MD_CTX *ctx, + const ASN1_ITEM *it, + void *asn, + X509_ALGOR *alg1, + X509_ALGOR *alg2, + ASN1_BIT_STRING *sig)); + + void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth, + int (*pkey_security_bits) (const EVP_PKEY + *pk)); + + const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey); + +=head1 DESCRIPTION + +B<EVP_PKEY_ASN1_METHOD> is a structure which holds a set of ASN.1 +conversion, printing and information methods for a specific public key +algorithm. + +There are two places where the B<EVP_PKEY_ASN1_METHOD> objects are +stored: one is a built-in array representing the standard methods for +different algorithms, and the other one is a stack of user-defined +application-specific methods, which can be manipulated by using +L<EVP_PKEY_asn1_add0(3)>. + +=head2 Methods + +The methods are the underlying implementations of a particular public +key algorithm present by the B<EVP_PKEY> object. + + int (*pub_decode) (EVP_PKEY *pk, X509_PUBKEY *pub); + int (*pub_encode) (X509_PUBKEY *pub, const EVP_PKEY *pk); + int (*pub_cmp) (const EVP_PKEY *a, const EVP_PKEY *b); + int (*pub_print) (BIO *out, const EVP_PKEY *pkey, int indent, + ASN1_PCTX *pctx); + +The pub_decode() and pub_encode() methods are called to decode / +encode B<X509_PUBKEY> ASN.1 parameters to / from B<pk>. +They MUST return 0 on error, 1 on success. +They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>. + +The pub_cmp() method is called when two public keys are to be +compared. +It MUST return 1 when the keys are equal, 0 otherwise. +It's called by L<EVP_PKEY_cmp(3)>. + +The pub_print() method is called to print a public key in humanly +readable text to B<out>, indented B<indent> spaces. +It MUST return 0 on error, 1 on success. +It's called by L<EVP_PKEY_print_public(3)>. + + int (*priv_decode) (EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf); + int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk); + int (*priv_print) (BIO *out, const EVP_PKEY *pkey, int indent, + ASN1_PCTX *pctx); + +The priv_decode() and priv_encode() methods are called to decode / +encode B<PKCS8_PRIV_KEY_INFO> form private key to / from B<pk>. +They MUST return 0 on error, 1 on success. +They're called by L<EVP_PKCS82PKEY(3)> and L<EVP_PKEY2PKCS8(3)>. + +The priv_print() method is called to print a private key in humanly +readable text to B<out>, indented B<indent> spaces. +It MUST return 0 on error, 1 on success. +It's called by L<EVP_PKEY_print_private(3)>. + + int (*pkey_size) (const EVP_PKEY *pk); + int (*pkey_bits) (const EVP_PKEY *pk); + int (*pkey_security_bits) (const EVP_PKEY *pk); + +The pkey_size() method returns the key size in bytes. +It's called by L<EVP_PKEY_size(3)>. + +The pkey_bits() method returns the key size in bits. +It's called by L<EVP_PKEY_bits(3)>. + + int (*param_decode) (EVP_PKEY *pkey, + const unsigned char **pder, int derlen); + int (*param_encode) (const EVP_PKEY *pkey, unsigned char **pder); + int (*param_missing) (const EVP_PKEY *pk); + int (*param_copy) (EVP_PKEY *to, const EVP_PKEY *from); + int (*param_cmp) (const EVP_PKEY *a, const EVP_PKEY *b); + int (*param_print) (BIO *out, const EVP_PKEY *pkey, int indent, + ASN1_PCTX *pctx); + +The param_decode() and param_encode() methods are called to decode / +encode DER formatted parameters to / from B<pk>. +They MUST return 0 on error, 1 on success. +They're called by L<PEM_read_bio_Parameters(3)> and the B<file:> +L<OSSL_STORE_LOADER(3)>. + +The param_missing() method returns 0 if a key parameter is missing, +otherwise 1. +It's called by L<EVP_PKEY_missing_parameters(3)>. + +The param_copy() method copies key parameters from B<from> to B<to>. +It MUST return 0 on error, 1 on success. +It's called by L<EVP_PKEY_copy_parameters(3)>. + +The param_cmp() method compares the parameters of keys B<a> and B<b>. +It MUST return 1 when the keys are equal, 0 when not equal, or a +negative number on error. +It's called by L<EVP_PKEY_cmp_parameters(3)>. + +The param_print() method prints the private key parameters in humanly +readable text to B<out>, indented B<indent> spaces. +It MUST return 0 on error, 1 on success. +It's called by L<EVP_PKEY_print_params(3)>. + + int (*sig_print) (BIO *out, + const X509_ALGOR *sigalg, const ASN1_STRING *sig, + int indent, ASN1_PCTX *pctx); + +The sig_print() method prints a signature in humanly readable text to +B<out>, indented B<indent> spaces. +B<sigalg> contains the exact signature algorithm. +If the signature in B<sig> doesn't correspond to what this method +expects, X509_signature_dump() must be used as a last resort. +It MUST return 0 on error, 1 on success. +It's called by L<X509_signature_print(3)>. + + void (*pkey_free) (EVP_PKEY *pkey); + +The pkey_free() method helps freeing the internals of B<pkey>. +It's called by L<EVP_PKEY_free(3)>, L<EVP_PKEY_set_type(3)>, +L<EVP_PKEY_set_type_str(3)>, and L<EVP_PKEY_assign(3)>. + + int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2); + +The pkey_ctrl() method adds extra algorithm specific control. +It's called by L<EVP_PKEY_get_default_digest_nid(3)>, +L<EVP_PKEY_set1_tls_encodedpoint(3)>, +L<EVP_PKEY_get1_tls_encodedpoint(3)>, L<PKCS7_SIGNER_INFO_set(3)>, +L<PKCS7_RECIP_INFO_set(3)>, ... + + int (*old_priv_decode) (EVP_PKEY *pkey, + const unsigned char **pder, int derlen); + int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder); + +The old_priv_decode() and old_priv_encode() methods decode / encode +they private key B<pkey> from / to a DER formatted array. +These are exclusively used to help decoding / encoding older (pre +PKCS#8) PEM formatted encrypted private keys. +old_priv_decode() MUST return 0 on error, 1 on success. +old_priv_encode() MUST the return same kind of values as +i2d_PrivateKey(). +They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>. + + int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn, + X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey); + int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn, + X509_ALGOR *alg1, X509_ALGOR *alg2, + ASN1_BIT_STRING *sig); + +The item_sign() and item_verify() methods make it possible to have +algorithm specific signatures and verification of them. + +item_sign() MUST return one of: + +=over 4 + +=item <=0 + +error + +=item Z<>1 + +item_sign() did everything, OpenSSL internals just needs to pass the +signature length back. + +=item Z<>2 + +item_sign() did nothing, OpenSSL internal standard routines are +expected to continue with the default signature production. + +=item Z<>3 + +item_sign() set the algorithm identifier B<algor1> and B<algor2>, +OpenSSL internals should just sign using those algorithms. + +=back + +item_verify() MUST return one of: + +=over 4 + +=item <=0 + +error + +=item Z<>1 + +item_sign() did everything, OpenSSL internals just needs to pass the +signature length back. + +=item Z<>2 + +item_sign() did nothing, OpenSSL internal standard routines are +expected to continue with the default signature production. + +=back + +item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and +L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>, +L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ... + +=head2 Functions + +EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD> +object, and associates the given B<id>, B<flags>, B<pem_str> and +B<info>. +B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a +descriptive string. +The following B<flags> are supported: + + ASN1_PKEY_SIGPARAM_NULL + +If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm +parameters are given the type B<V_ASN1_NULL> by default, otherwise +they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is +omitted). +See L<X509_ALGOR_set0(3)> for more information. + +EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from +B<src> to B<dst>. +This function is not thread safe, it's recommended to only use this +when initializing the application. + +EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed +by B<ameth>. + +EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of +methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is +already there. +This function is not thread safe, it's recommended to only use this +when initializing the application. + +EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the +B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another +B<EVP_PKEY_ASN1_METHOD> with the same NID is already added. +This function is not thread safe, it's recommended to only use this +when initializing the application. + +EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(), +EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(), +EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(), and +EVP_PKEY_asn1_set_security_bits() set the diverse methods of the given +B<EVP_PKEY_ASN1_METHOD> object. + +EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated +with the key B<pkey>. + +=head1 RETURN VALUES + +EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an +B<EVP_PKEY_ASN1_METHOD> object otherwise. + +EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error, +or 1 on success. + +EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant +B<EVP_PKEY_ASN1_METHOD> object otherwise. + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_ctrl.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_ctrl.pod new file mode 100644 index 0000000..a30450b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_ctrl.pod @@ -0,0 +1,154 @@ +=pod + +=head1 NAME + +EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, +EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding, +EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits, +EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits, +EVP_PKEY_CTX_set_dh_paramgen_prime_len, +EVP_PKEY_CTX_set_dh_paramgen_generator, +EVP_PKEY_CTX_set_ec_paramgen_curve_nid, +EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, + int cmd, int p1, void *p2); + int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, + const char *value); + + #include <openssl/rsa.h> + + int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); + + int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); + int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); + int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); + + #include <openssl/dsa.h> + int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); + + #include <openssl/dh.h> + int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); + int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); + + #include <openssl/ec.h> + int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); + int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); + +=head1 DESCRIPTION + +The function EVP_PKEY_CTX_ctrl() sends a control operation to the context +B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter +B<optype> is a mask indicating which operations the control can be applied to. +The control command is indicated in B<cmd> and any additional arguments in +B<p1> and B<p2>. + +Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will +instead call one of the algorithm specific macros below. + +The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm +specific control operation to a context B<ctx> in string form. This is +intended to be used for options specified on the command line or in text +files. The commands supported are documented in the openssl utility +command line pages for the option B<-pkeyopt> which is supported by the +B<pkeyutl>, B<genpkey> and B<req> commands. + +All the remaining "functions" are implemented as macros. + +The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used +in a signature. It can be used with any public key algorithm supporting +signature operations. + +The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>. +The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, +RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, +RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), +RSA_X931_PADDING for X9.31 padding (signature operations only) and +RSA_PKCS1_PSS_PADDING (sign and verify only). + +Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() +is used. If this macro is called for PKCS#1 padding the plaintext buffer is +an actual digest value and is encapsulated in a DigestInfo structure according +to PKCS#1 when signing and this structure is expected (and stripped off) when +verifying. If this control is not used with RSA and PKCS#1 padding then the +supplied data is used directly and not encapsulated. In the case of X9.31 +padding for RSA the algorithm identifier byte is added or checked and removed +if this control is called. If it is not called then the first byte of the plaintext +buffer is expected to be the algorithm identifier byte. + +The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to +B<len> as its name implies it is only supported for PSS padding. Two special +values are supported: -1 sets the salt length to the digest length. When +signing -2 sets the salt length to the maximum permissible value. When +verifying -2 causes the salt length to be automatically determined based on the +B<PSS> block structure. If this macro is not called a salt length value of -2 +is used by default. + +The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for +RSA key generation to B<bits>. If not specified 1024 bits is used. + +The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value +for RSA key generation to B<pubexp> currently it should be an odd integer. The +B<pubexp> pointer is used internally by this function so it should not be +modified or free after the call. If this macro is not called then 65537 is used. + +The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used +for DSA parameter generation to B<bits>. If not specified 1024 is used. + +The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH +prime parameter B<p> for DH parameter generation. If this macro is not called +then 1024 is used. + +The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen> +for DH parameter generation. If not specified 2 is used. + +The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter +generation to B<nid>. For EC parameter generation this macro must be called +or an error occurs because there is no default curve. +This function can also be called to set the curve explicitly when +generating an EC key. + +The EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to +B<param_enc> when generating EC parameters or an EC key. The encoding can be +B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions +of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form. +For maximum compatibility the named curve form should be used. Note: the +B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous +versions should use 0 instead. + +=head1 RETURN VALUES + +EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> +L<EVP_PKEY_keygen(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_new.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_new.pod new file mode 100644 index 0000000..eff94cd --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_new.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - public key algorithm context functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); + EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); + EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx); + void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); + +=head1 DESCRIPTION + +The EVP_PKEY_CTX_new() function allocates public key algorithm context using +the algorithm specified in B<pkey> and ENGINE B<e>. + +The EVP_PKEY_CTX_new_id() function allocates public key algorithm context +using the algorithm specified by B<id> and ENGINE B<e>. It is normally used +when no B<EVP_PKEY> structure is associated with the operations, for example +during parameter generation of key generation for some algorithms. + +EVP_PKEY_CTX_dup() duplicates the context B<ctx>. + +EVP_PKEY_CTX_free() frees up the context B<ctx>. +If B<ctx> is NULL, nothing is done. + +=head1 NOTES + +The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used +by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between +threads: that is it is not permissible to use the same context simultaneously +in two threads. + +=head1 RETURN VALUES + +EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either +the newly allocated B<EVP_PKEY_CTX> structure of B<NULL> if an error occurred. + +EVP_PKEY_CTX_free() does not return a value. + +=head1 SEE ALSO + +L<EVP_PKEY_new(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod new file mode 100644 index 0000000..61e0eec --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt, +EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info - +HMAC-based Extract-and-Expand key derivation algorithm + +=head1 SYNOPSIS + + #include <openssl/kdf.h> + + int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md); + + int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt, + int saltlen); + + int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key, + int keylen); + + int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info, + int infolen); + +=head1 DESCRIPTION + +The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function. +HKDF follows the "extract-then-expand" paradigm, where the KDF logically +consists of two modules. The first stage takes the input keying material +and "extracts" from it a fixed-length pseudorandom key K. The second stage +"expands" the key K into several additional pseudorandom keys (the output +of the KDF). + +EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF. + +EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the +buffer B<salt>. Any existing value is replaced. + +EVP_PKEY_CTX_set_hkdf_key() sets the key to B<keylen> bytes of the buffer +B<key>. Any existing value is replaced. + +EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the +buffer B<info>. If a value is already set, it is appended to the existing +value. + +=head1 STRING CTRLS + +HKDF also supports string based control operations via +L<EVP_PKEY_CTX_ctrl_str(3)>. +The B<type> parameter "md" uses the supplied B<value> as the name of the digest +algorithm to use. +The B<type> parameters "salt", "key" and "info" use the supplied B<value> +parameter as a B<seed>, B<key> or B<info> value. +The names "hexsalt", "hexkey" and "hexinfo" are similar except they take a hex +string which is converted to binary. + +=head1 NOTES + +All these functions are implemented as macros. + +A context for HKDF can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_HKDF, NULL); + +The digest, key, salt and info values must be set before a key is derived or +an error occurs. + +The total length of the info buffer cannot exceed 1024 bytes in length: this +should be more than enough for any normal use of HKDF. + +The output length of the KDF is specified via the length parameter to the +L<EVP_PKEY_derive(3)> function. +Since the HKDF output length is variable, passing a B<NULL> buffer as a means +to obtain the requisite length is not meaningful with HKDF. +Instead, the caller must allocate a buffer of the desired length, and pass that +buffer to L<EVP_PKEY_derive(3)> along with (a pointer initialized to) the +desired length. + +Optimised versions of HKDF can be implemented in an ENGINE. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLE + +This example derives 10 bytes using SHA-256 with the secret key "secret", +salt value "salt" and info value "label": + + EVP_PKEY_CTX *pctx; + unsigned char out[10]; + size_t outlen = sizeof(out); + pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL); + + if (EVP_PKEY_derive_init(pctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set1_salt(pctx, "salt", 4) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set1_key(pctx, "secret", 6) <= 0) + /* Error */ + if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 6) <= 0) + /* Error */ + if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) + /* Error */ + +=head1 CONFORMING TO + +RFC 5869 + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl_str(3)>, +L<EVP_PKEY_derive(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod new file mode 100644 index 0000000..f1f0ae4 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod @@ -0,0 +1,108 @@ +=pod + +=head1 NAME + +EVP_PKEY_CTX_set_tls1_prf_md, +EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed - +TLS PRF key derivation algorithm + +=head1 SYNOPSIS + + #include <openssl/kdf.h> + + int EVP_PKEY_CTX_set_tls1_prf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md); + int EVP_PKEY_CTX_set1_tls1_prf_secret(EVP_PKEY_CTX *pctx, + unsigned char *sec, int seclen); + int EVP_PKEY_CTX_add1_tls1_prf_seed(EVP_PKEY_CTX *pctx, + unsigned char *seed, int seedlen); + +=head1 DESCRIPTION + +The B<EVP_PKEY_TLS1_PRF> algorithm implements the PRF key derivation function for +TLS. It has no associated private key and only implements key derivation +using L<EVP_PKEY_derive(3)>. + +EVP_PKEY_set_tls1_prf_md() sets the message digest associated with the +TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF +algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1. + +EVP_PKEY_CTX_set_tls1_prf_secret() sets the secret value of the TLS PRF +to B<seclen> bytes of the buffer B<sec>. Any existing secret value is replaced +and any seed is reset. + +EVP_PKEY_CTX_add1_tls1_prf_seed() sets the seed to B<seedlen> bytes of B<seed>. +If a seed is already set it is appended to the existing value. + +=head1 STRING CTRLS + +The TLS PRF also supports string based control operations using +L<EVP_PKEY_CTX_ctrl_str(3)>. +The B<type> parameter "md" uses the supplied B<value> as the name of the digest +algorithm to use. +The B<type> parameters "secret" and "seed" use the supplied B<value> parameter +as a secret or seed value. +The names "hexsecret" and "hexseed" are similar except they take a hex string +which is converted to binary. + +=head1 NOTES + +All these functions are implemented as macros. + +A context for the TLS PRF can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_TLS1_PRF, NULL); + +The digest, secret value and seed must be set before a key is derived or an +error occurs. + +The total length of all seeds cannot exceed 1024 bytes in length: this should +be more than enough for any normal use of the TLS PRF. + +The output length of the PRF is specified by the length parameter in the +EVP_PKEY_derive() function. Since the output length is variable, setting +the buffer to B<NULL> is not meaningful for the TLS PRF. + +Optimised versions of the TLS PRF can be implemented in an ENGINE. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLE + +This example derives 10 bytes using SHA-256 with the secret key "secret" +and seed value "seed": + + EVP_PKEY_CTX *pctx; + unsigned char out[10]; + size_t outlen = sizeof(out); + pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); + if (EVP_PKEY_derive_init(pctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, "secret", 6) <= 0) + /* Error */ + if (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, "seed", 4) <= 0) + /* Error */ + if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) + /* Error */ + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl_str(3)>, +L<EVP_PKEY_derive(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_asn1_get_count.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_asn1_get_count.pod new file mode 100644 index 0000000..9ad2dae --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_asn1_get_count.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +EVP_PKEY_asn1_find, +EVP_PKEY_asn1_find_str, +EVP_PKEY_asn1_get_count, +EVP_PKEY_asn1_get0, +EVP_PKEY_asn1_get0_info +- enumerate public key ASN.1 methods + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_asn1_get_count(void); + const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_get0(int idx); + const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find(ENGINE **pe, int type); + const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find_str(ENGINE **pe, + const char *str, int len); + int EVP_PKEY_asn1_get0_info(int *ppkey_id, int *pkey_base_id, + int *ppkey_flags, const char **pinfo, + const char **ppem_str, + const EVP_PKEY_ASN1_METHOD *ameth); + +=head1 DESCRIPTION + +EVP_PKEY_asn1_count() returns a count of the number of public key +ASN.1 methods available: it includes standard methods and any methods +added by the application. + +EVP_PKEY_asn1_get0() returns the public key ASN.1 method B<idx>. +The value of B<idx> must be between zero and EVP_PKEY_asn1_get_count() +- 1. + +EVP_PKEY_asn1_find() looks up the B<EVP_PKEY_ASN1_METHOD> with NID +B<type>. +If B<pe> isn't B<NULL>, then it will look up an engine implementing a +B<EVP_PKEY_ASN1_METHOD> for the NID B<type> and return that instead, +and also set B<*pe> to point at the engine that implements it. + +EVP_PKEY_asn1_find_str() looks up the B<EVP_PKEY_ASN1_METHOD> with PEM +type string B<str>. +Just like EVP_PKEY_asn1_find(), if B<pe> isn't B<NULL>, then it will +look up an engine implementing a B<EVP_PKEY_ASN1_METHOD> for the NID +B<type> and return that instead, and also set B<*pe> to point at the +engine that implements it. + +EVP_PKEY_asn1_get0_info() returns the public key ID, base public key +ID (both NIDs), any flags, the method description and PEM type string +associated with the public key ASN.1 method B<*ameth>. + +EVP_PKEY_asn1_count(), EVP_PKEY_asn1_get0(), EVP_PKEY_asn1_find() and +EVP_PKEY_asn1_find_str() are not thread safe, but as long as all +B<EVP_PKEY_ASN1_METHOD> objects are added before the application gets +threaded, using them is safe. See L<EVP_PKEY_asn1_add0(3)>. + +=head1 RETURN VALUES + +EVP_PKEY_asn1_count() returns the number of available public key methods. + +EVP_PKEY_asn1_get0() return a public key method or B<NULL> if B<idx> is +out of range. + +EVP_PKEY_asn1_get0_info() returns 0 on failure, 1 on success. + +=head1 SEE ALSO + +L<EVP_PKEY_asn1_new(3)>, L<EVP_PKEY_asn1_add0(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_cmp.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_cmp.pod new file mode 100644 index 0000000..270d635 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_cmp.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters, +EVP_PKEY_cmp - public key parameter and comparison functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); + int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); + + int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); + int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); + +=head1 DESCRIPTION + +The function EVP_PKEY_missing_parameters() returns 1 if the public key +parameters of B<pkey> are missing and 0 if they are present or the algorithm +doesn't use parameters. + +The function EVP_PKEY_copy_parameters() copies the parameters from key +B<from> to key B<to>. An error is returned if the parameters are missing in +B<from> or present in both B<from> and B<to> and mismatch. If the parameters +in B<from> and B<to> are both present and match this function has no effect. + +The function EVP_PKEY_cmp_parameters() compares the parameters of keys +B<a> and B<b>. + +The function EVP_PKEY_cmp() compares the public key components and parameters +(if present) of keys B<a> and B<b>. + +=head1 NOTES + +The main purpose of the functions EVP_PKEY_missing_parameters() and +EVP_PKEY_copy_parameters() is to handle public keys in certificates where the +parameters are sometimes omitted from a public key if they are inherited from +the CA that signed it. + +Since OpenSSL private keys contain public key components too the function +EVP_PKEY_cmp() can also be used to determine if a private key matches +a public key. + +=head1 RETURN VALUES + +The function EVP_PKEY_missing_parameters() returns 1 if the public key +parameters of B<pkey> are missing and 0 if they are present or the algorithm +doesn't use parameters. + +These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for +failure. + +The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the +keys match, 0 if they don't match, -1 if the key types are different and +-2 if the operation is not supported. + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_keygen(3)> + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_decrypt.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_decrypt.pod new file mode 100644 index 0000000..ca732ed --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_decrypt.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, + unsigned char *out, size_t *outlen, + const unsigned char *in, size_t inlen); + +=head1 DESCRIPTION + +The EVP_PKEY_decrypt_init() function initializes a public key algorithm +context using key B<pkey> for a decryption operation. + +The EVP_PKEY_decrypt() function performs a public key decryption operation +using B<ctx>. The data to be decrypted is specified using the B<in> and +B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output +buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then +before the call the B<outlen> parameter should contain the length of the +B<out> buffer, if the call is successful the decrypted data is written to +B<out> and the amount of data written to B<outlen>. + +=head1 NOTES + +After the call to EVP_PKEY_decrypt_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_decrypt() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Decrypt data using OAEP (for RSA keys): + + #include <openssl/evp.h> + #include <openssl/rsa.h> + + EVP_PKEY_CTX *ctx; + unsigned char *out, *in; + size_t outlen, inlen; + EVP_PKEY *key; + /* NB: assumes key in, inlen are already set up + * and that key is an RSA private key + */ + ctx = EVP_PKEY_CTX_new(key); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_decrypt_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0) + /* Error */ + + out = OPENSSL_malloc(outlen); + + if (!out) + /* malloc failure */ + + if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0) + /* Error */ + + /* Decrypted data is outlen bytes written to buffer out */ + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_derive.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_derive.pod new file mode 100644 index 0000000..f70a0b8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_derive.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); + int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); + +=head1 DESCRIPTION + +The EVP_PKEY_derive_init() function initializes a public key algorithm +context using key B<pkey> for shared secret derivation. + +The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally +be a public key. + +The EVP_PKEY_derive() derives a shared secret using B<ctx>. +If B<key> is B<NULL> then the maximum size of the output buffer is written to +the B<keylen> parameter. If B<key> is not B<NULL> then before the call the +B<keylen> parameter should contain the length of the B<key> buffer, if the call +is successful the shared secret is written to B<key> and the amount of data +written to B<keylen>. + +=head1 NOTES + +After the call to EVP_PKEY_derive_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_derive() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Derive shared secret (for example DH or EC keys): + + #include <openssl/evp.h> + #include <openssl/rsa.h> + + EVP_PKEY_CTX *ctx; + unsigned char *skey; + size_t skeylen; + EVP_PKEY *pkey, *peerkey; + /* NB: assumes pkey, peerkey have been already set up */ + + ctx = EVP_PKEY_CTX_new(pkey); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_derive_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) + /* Error */ + + skey = OPENSSL_malloc(skeylen); + + if (!skey) + /* malloc failure */ + + if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) + /* Error */ + + /* Shared secret is skey bytes written to buffer skey */ + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_encrypt.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_encrypt.pod new file mode 100644 index 0000000..01336e1 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_encrypt.pod @@ -0,0 +1,108 @@ +=pod + +=head1 NAME + +EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, + unsigned char *out, size_t *outlen, + const unsigned char *in, size_t inlen); + +=head1 DESCRIPTION + +The EVP_PKEY_encrypt_init() function initializes a public key algorithm +context using key B<pkey> for an encryption operation. + +The EVP_PKEY_encrypt() function performs a public key encryption operation +using B<ctx>. The data to be encrypted is specified using the B<in> and +B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output +buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then +before the call the B<outlen> parameter should contain the length of the +B<out> buffer, if the call is successful the encrypted data is written to +B<out> and the amount of data written to B<outlen>. + +=head1 NOTES + +After the call to EVP_PKEY_encrypt_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_encrypt() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or +L<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 eng, key, in, inlen are already set up, + * and that key is an RSA public key + */ + ctx = EVP_PKEY_CTX_new(key, eng); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_encrypt_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0) + /* Error */ + + out = OPENSSL_malloc(outlen); + + if (!out) + /* malloc failure */ + + if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0) + /* Error */ + + /* Encrypted data is outlen bytes written to buffer out */ + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<engine(3)>, +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_get_default_digest_nid.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_get_default_digest_nid.pod new file mode 100644 index 0000000..3dce5c5 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_get_default_digest_nid.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +EVP_PKEY_get_default_digest_nid - get default signature digest + +=head1 SYNOPSIS + + #include <openssl/evp.h> + int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); + +=head1 DESCRIPTION + +The EVP_PKEY_get_default_digest_nid() function sets B<pnid> to the default +message digest NID for the public key signature operations associated with key +B<pkey>. + +=head1 NOTES + +For all current standard OpenSSL public key algorithms SHA1 is returned. + +=head1 RETURN VALUES + +The EVP_PKEY_get_default_digest_nid() function returns 1 if the message digest +is advisory (that is other digests can be used) and 2 if it is mandatory (other +digests can not be used). It returns 0 or a negative value for failure. In +particular a return value of -2 indicates the operation is not supported by the +public key algorithm. + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, + +=head1 HISTORY + +This function was first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_keygen.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_keygen.pod new file mode 100644 index 0000000..b1e708f --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_keygen.pod @@ -0,0 +1,175 @@ +=pod + +=head1 NAME + +EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, +EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, +EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, +EVP_PKEY_CTX_get_app_data, +EVP_PKEY_gen_cb +- key and parameter generation functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); + int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); + + typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); + + void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); + EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); + + int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); + + void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); + void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); + +=head1 DESCRIPTION + +The EVP_PKEY_keygen_init() function initializes a public key algorithm +context using key B<pkey> for a key generation operation. + +The EVP_PKEY_keygen() function performs a key generation operation, the +generated key is written to B<ppkey>. + +The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar +except parameters are generated. + +The function EVP_PKEY_set_cb() sets the key or parameter generation callback +to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter +generation callback. + +The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated +with the generation operation. If B<idx> is -1 the total number of +parameters available is returned. Any non negative value returns the value of +that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for +B<idx> should only be called within the generation callback. + +If the callback returns 0 then the key generation operation is aborted and an +error occurs. This might occur during a time consuming operation where +a user clicks on a "cancel" button. + +The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set +and retrieve an opaque pointer. This can be used to set some application +defined value which can be retrieved in the callback: for example a handle +which is used to update a "progress dialog". + +=head1 NOTES + +After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm +specific control operations can be performed to set any appropriate parameters +for the operation. + +The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than +once on the same context if several operations are performed using the same +parameters. + +The meaning of the parameters passed to the callback will depend on the +algorithm and the specific implementation of the algorithm. Some might not +give any useful information at all during key or parameter generation. Others +might not even call the callback. + +The operation performed by key or parameter generation depends on the algorithm +used. In some cases (e.g. EC with a supplied named curve) the "generation" +option merely sets the appropriate fields in an EVP_PKEY structure. + +In OpenSSL an EVP_PKEY structure containing a private key also contains the +public key components and parameters (if any). An OpenSSL private key is +equivalent to what some libraries call a "key pair". A private key can be used +in functions which require the use of a public key or parameters. + +=head1 RETURN VALUES + +EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and +EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLES + +Generate a 2048 bit RSA key: + + #include <openssl/evp.h> + #include <openssl/rsa.h> + + EVP_PKEY_CTX *ctx; + EVP_PKEY *pkey = NULL; + ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_keygen_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) + /* Error */ + + /* Generate key */ + if (EVP_PKEY_keygen(ctx, &pkey) <= 0) + /* Error */ + +Generate a key from a set of parameters: + + #include <openssl/evp.h> + #include <openssl/rsa.h> + + EVP_PKEY_CTX *ctx; + EVP_PKEY *pkey = NULL, *param; + /* Assumed param is set up already */ + ctx = EVP_PKEY_CTX_new(param); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_keygen_init(ctx) <= 0) + /* Error */ + + /* Generate key */ + if (EVP_PKEY_keygen(ctx, &pkey) <= 0) + /* Error */ + +Example of generation callback for OpenSSL public key implementations: + + /* Application data is a BIO to output status to */ + + EVP_PKEY_CTX_set_app_data(ctx, status_bio); + + static int genpkey_cb(EVP_PKEY_CTX *ctx) + { + char c = '*'; + BIO *b = EVP_PKEY_CTX_get_app_data(ctx); + int p; + p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); + if (p == 0) c = '.'; + if (p == 1) c = '+'; + if (p == 2) c = '*'; + if (p == 3) c = '\n'; + BIO_write(b, &c, 1); + (void)BIO_flush(b); + return 1; + } + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_new.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_new.pod new file mode 100644 index 0000000..956d699 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_new.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_free - private key allocation functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_PKEY *EVP_PKEY_new(void); + int EVP_PKEY_up_ref(EVP_PKEY *key); + void EVP_PKEY_free(EVP_PKEY *key); + + +=head1 DESCRIPTION + +The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is +used by OpenSSL to store private keys. The reference count is set to B<1>. + +EVP_PKEY_up_ref() increments the reference count of B<key>. + +EVP_PKEY_free() decrements the reference count of B<key> and, if the reference +count is zero, frees it up. If B<key> is NULL, nothing is done. + +=head1 NOTES + +The B<EVP_PKEY> structure is used by various OpenSSL functions which require a +general private key without reference to any particular algorithm. + +The structure returned by EVP_PKEY_new() is empty. To add a private key to this +empty structure the functions described in L<EVP_PKEY_set1_RSA(3)> should be +used. + +=head1 RETURN VALUES + +EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> structure or +B<NULL> if an error occurred. + +EVP_PKEY_up_ref() returns 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<EVP_PKEY_set1_RSA(3)> + +=head1 HISTORY + +EVP_PKEY_new() and EVP_PKEY_free() exist in all versions of OpenSSL. + +EVP_PKEY_up_ref() was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_print_private.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_print_private.pod new file mode 100644 index 0000000..9f1d324 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_print_private.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public key algorithm printing routines + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, + int indent, ASN1_PCTX *pctx); + int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, + int indent, ASN1_PCTX *pctx); + int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, + int indent, ASN1_PCTX *pctx); + +=head1 DESCRIPTION + +The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and +EVP_PKEY_print_params() print out the public, private or parameter components +of key B<pkey> respectively. The key is sent to BIO B<out> in human readable +form. The parameter B<indent> indicated how far the printout should be indented. + +The B<pctx> parameter allows the print output to be finely tuned by using +ASN1 printing options. If B<pctx> is set to NULL then default values will +be used. + +=head1 NOTES + +Currently no public key algorithms include any options in the B<pctx> parameter +parameter. + +If the key does not include all the components indicated by the function then +only those contained in the key will be printed. For example passing a public +key to EVP_PKEY_print_private() will only print the public components. + +=head1 RETURN VALUES + +These functions all return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_keygen(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_set1_RSA.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_set1_RSA.pod new file mode 100644 index 0000000..884cf91 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_set1_RSA.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, +EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, +EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, +EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, +EVP_PKEY_assign_EC_KEY, EVP_PKEY_get0_hmac, EVP_PKEY_type, EVP_PKEY_id, +EVP_PKEY_base_id, EVP_PKEY_set1_engine - EVP_PKEY assignment functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key); + int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key); + int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key); + int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); + + RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); + DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); + DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey); + EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); + + const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len); + RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey); + DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey); + DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey); + EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey); + + int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key); + int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key); + int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key); + int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); + + int EVP_PKEY_id(const EVP_PKEY *pkey); + int EVP_PKEY_base_id(const EVP_PKEY *pkey); + int EVP_PKEY_type(int type); + + int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine); + +=head1 DESCRIPTION + +EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and +EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>. + +EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and +EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or +B<NULL> if the key is not of the correct type. + +EVP_PKEY_get0_hmac(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), +EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() also return the +referenced key in B<pkey> or B<NULL> if the key is not of the +correct type but the reference count of the returned key is +B<not> incremented and so must not be freed up after use. + +EVP_PKEY_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. + +EVP_PKEY_base_id() returns the type of B<pkey>. For example +an RSA key will return B<EVP_PKEY_RSA>. + +EVP_PKEY_id() returns the actual OID associated with B<pkey>. Historically keys +using the same algorithm could use different OIDs. For example an RSA key could +use the OIDs corresponding to the NIDs B<NID_rsaEncryption> (equivalent to +B<EVP_PKEY_RSA>) or B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of +alternative non-standard OIDs is now rare so B<EVP_PKEY_RSA2> et al are not +often seen in practice. + +EVP_PKEY_type() returns the underlying type of the NID B<type>. For example +EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>. + +EVP_PKEY_set1_engine() sets the ENGINE handling B<pkey> to B<engine>. It +must be called after the key algorithm and components are set up. +If B<engine> does not include an B<EVP_PKEY_METHOD> for B<pkey> an +error occurs. + +=head1 NOTES + +In accordance with the OpenSSL naming convention the key obtained +from or assigned to the B<pkey> using the B<1> functions must be +freed as well as B<pkey>. + +EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() +and EVP_PKEY_assign_EC_KEY() are implemented as macros. + +Most applications wishing to know a key type will simply call +EVP_PKEY_base_id() and will not care about the actual type: +which will be identical in almost all cases. + +Previous versions of this document suggested using EVP_PKEY_type(pkey->type) +to determine the type of a key. Since B<EVP_PKEY> is now opaque this +is no longer possible: the equivalent is EVP_PKEY_base_id(pkey). + +EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM +key as part of its routine to load a private key. + +=head1 RETURN VALUES + +EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and +EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure. + +EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and +EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if +an error occurred. + +EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() +and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure. + +EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key +type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error. + +EVP_PKEY_set1_engine() returns 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<EVP_PKEY_new(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_sign.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_sign.pod new file mode 100644 index 0000000..9b3c8d4 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_sign.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, + unsigned char *sig, size_t *siglen, + const unsigned char *tbs, size_t tbslen); + +=head1 DESCRIPTION + +The EVP_PKEY_sign_init() function initializes a public key algorithm +context using key B<pkey> for a signing operation. + +The EVP_PKEY_sign() function performs a public key signing operation +using B<ctx>. The data to be signed is specified using the B<tbs> and +B<tbslen> parameters. If B<sig> is B<NULL> then the maximum size of the output +buffer is written to the B<siglen> parameter. If B<sig> is not B<NULL> then +before the call the B<siglen> parameter should contain the length of the +B<sig> buffer, if the call is successful the signature is written to +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)> and +L<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 (see L<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. + +=head1 RETURN VALUES + +EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0 +or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Sign data using RSA with PKCS#1 padding and SHA256 digest: + + #include <openssl/evp.h> + #include <openssl/rsa.h> + + EVP_PKEY_CTX *ctx; + /* md is a SHA-256 digest in this example. */ + unsigned char *md, *sig; + size_t mdlen = 32, siglen; + EVP_PKEY *signing_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, NULL /* no engine */); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_sign_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0) + /* Error */ + + sig = OPENSSL_malloc(siglen); + + if (!sig) + /* malloc failure */ + + if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) + /* Error */ + + /* Signature is siglen bytes written to buffer sig */ + + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_verify.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_verify.pod new file mode 100644 index 0000000..e84f880 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_verify.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, + const unsigned char *sig, size_t siglen, + const unsigned char *tbs, size_t tbslen); + +=head1 DESCRIPTION + +The EVP_PKEY_verify_init() function initializes a public key algorithm +context using key B<pkey> for a signature verification operation. + +The EVP_PKEY_verify() function performs a public key verification operation +using B<ctx>. The signature is specified using the B<sig> and +B<siglen> parameters. The verified data (i.e. the data believed originally +signed) is specified using the B<tbs> and B<tbslen> parameters. + +=head1 NOTES + +After the call to EVP_PKEY_verify_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_verify() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was +successful and 0 if it failed. Unlike other functions the return value 0 from +EVP_PKEY_verify() only indicates that the signature did not not verify +successfully (that is tbs did not match the original data or the signature was +of invalid form) it is not an indication of a more serious error. + +A negative value indicates an error other that signature verification failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLE + +Verify signature using PKCS#1 and SHA256 digest: + + #include <openssl/evp.h> + #include <openssl/rsa.h> + + EVP_PKEY_CTX *ctx; + unsigned char *md, *sig; + size_t mdlen, siglen; + EVP_PKEY *verify_key; + /* NB: assumes verify_key, sig, siglen md and mdlen are already set up + * and that verify_key is an RSA public key + */ + ctx = EVP_PKEY_CTX_new(verify_key); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_verify_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) + /* Error */ + + /* Perform operation */ + ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); + + /* ret == 1 indicates success, 0 verify failure and < 0 for some + * other error. + */ + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_PKEY_verify_recover.pod b/openssl-1.1.0h/doc/crypto/EVP_PKEY_verify_recover.pod new file mode 100644 index 0000000..837bc64 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_PKEY_verify_recover.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); + int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx, + unsigned char *rout, size_t *routlen, + const unsigned char *sig, size_t siglen); + +=head1 DESCRIPTION + +The EVP_PKEY_verify_recover_init() function initializes a public key algorithm +context using key B<pkey> for a verify recover operation. + +The EVP_PKEY_verify_recover() function recovers signed data +using B<ctx>. The signature is specified using the B<sig> and +B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output +buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then +before the call the B<routlen> parameter should contain the length of the +B<rout> buffer, if the call is successful recovered data is written to +B<rout> and the amount of data written to B<routlen>. + +=head1 NOTES + +Normally an application is only interested in whether a signature verification +operation is successful in those cases the EVP_verify() function should be +used. + +Sometimes however it is useful to obtain the data originally signed using a +signing operation. Only certain public key algorithms can recover a signature +in this way (for example RSA in PKCS padding mode). + +After the call to EVP_PKEY_verify_recover_init() algorithm specific control +operations can be performed to set any appropriate parameters for the +operation. + +The function EVP_PKEY_verify_recover() can be called more than once on the same +context if several operations are performed using the same parameters. + +=head1 RETURN VALUES + +EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for success +and 0 or a negative value for failure. In particular a return value of -2 +indicates the operation is not supported by the public key algorithm. + +=head1 EXAMPLE + +Recover digest originally signed using PKCS#1 and SHA256 digest: + + #include <openssl/evp.h> + #include <openssl/rsa.h> + + EVP_PKEY_CTX *ctx; + unsigned char *rout, *sig; + size_t routlen, siglen; + EVP_PKEY *verify_key; + /* NB: assumes verify_key, sig and siglen are already set up + * and that verify_key is an RSA public key + */ + ctx = EVP_PKEY_CTX_new(verify_key); + if (!ctx) + /* Error occurred */ + if (EVP_PKEY_verify_recover_init(ctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) + /* Error */ + + /* Determine buffer length */ + if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0) + /* Error */ + + rout = OPENSSL_malloc(routlen); + + if (!rout) + /* malloc failure */ + + if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0) + /* Error */ + + /* Recovered data is routlen bytes written to buffer rout */ + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_derive(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_SealInit.pod b/openssl-1.1.0h/doc/crypto/EVP_SealInit.pod new file mode 100644 index 0000000..30bd680 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_SealInit.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, + unsigned char **ek, int *ekl, unsigned char *iv, + EVP_PKEY **pubk, int npubk); + int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl, unsigned char *in, int inl); + int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, + int *outl); + +=head1 DESCRIPTION + +The EVP envelope routines are a high level interface to envelope +encryption. They generate a random key and IV (if required) then +"envelope" it by using public key encryption. Data can then be +encrypted using this key. + +EVP_SealInit() initializes a cipher context B<ctx> for encryption +with cipher B<type> using a random secret key and IV. B<type> is normally +supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted +using one or more public keys, this allows the same encrypted data to be +decrypted using any of the corresponding private keys. B<ek> is an array of +buffers where the public key encrypted secret key will be written, each buffer +must contain enough room for the corresponding encrypted key: that is +B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual +size of each encrypted secret key is written to the array B<ekl>. B<pubk> is +an array of B<npubk> public keys. + +The B<iv> parameter is a buffer where the generated IV is written to. It must +contain enough room for the corresponding cipher's IV, as determined by (for +example) EVP_CIPHER_iv_length(type). + +If the cipher does not require an IV then the B<iv> parameter is ignored +and can be B<NULL>. + +EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties +as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as +documented on the L<EVP_EncryptInit(3)> manual +page. + +=head1 RETURN VALUES + +EVP_SealInit() returns 0 on error or B<npubk> if successful. + +EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for +failure. + +=head1 NOTES + +Because a random secret key is generated the random number generator +must be seeded before calling EVP_SealInit(). + +The public key must be RSA because it is the only OpenSSL public key +algorithm that supports key transport. + +Envelope encryption is the usual method of using public key encryption +on large amounts of data, this is because public key encryption is slow +but symmetric encryption is fast. So symmetric encryption is used for +bulk encryption and the small random symmetric key used is transferred +using public key encryption. + +It is possible to call EVP_SealInit() twice in the same way as +EVP_EncryptInit(). The first call should have B<npubk> set to 0 +and (after setting any cipher parameters) it should be called again +with B<type> set to NULL. + +=head1 SEE ALSO + +L<evp(3)>, L<rand(3)>, +L<EVP_EncryptInit(3)>, +L<EVP_OpenInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_SignInit.pod b/openssl-1.1.0h/doc/crypto/EVP_SignInit.pod new file mode 100644 index 0000000..21eb868 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_SignInit.pod @@ -0,0 +1,105 @@ +=pod + +=head1 NAME + +EVP_PKEY_size, +EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal - EVP signing +functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); + int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s, EVP_PKEY *pkey); + + void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); + + int EVP_PKEY_size(EVP_PKEY *pkey); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital +signatures. + +EVP_SignInit_ex() sets up signing context B<ctx> to use digest +B<type> from ENGINE B<impl>. B<ctx> must be created with +EVP_MD_CTX_new() before calling this function. + +EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the +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>. B<sig> must be at least EVP_PKEY_size(pkey) +bytes in size. B<s> is an OUT parameter, and not used as an IN parameter. +The number of bytes of data written (i.e. the length of the signature) +will be written to the integer at 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>. + +EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual +signature returned by EVP_SignFinal() may be smaller. + +=head1 RETURN VALUES + +EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1 +for success and 0 for failure. + +EVP_PKEY_size() returns the maximum size of a signature in bytes. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +When signing with DSA private keys the random number generator must be seeded +or the operation will fail. The random number generator does not need to be +seeded for RSA signatures. + +The call to EVP_SignFinal() internally finalizes a copy of the digest context. +This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called +later to digest and sign additional data. + +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak +will occur. + +=head1 BUGS + +Older versions of this documentation wrongly stated that calls to +EVP_SignUpdate() could not be made after calling EVP_SignFinal(). + +Since the private key is passed in the call to EVP_SignFinal() any error +relating to the private key (for example an unsuitable key and digest +combination) will not be indicated until after potentially large amounts of +data have been passed through EVP_SignUpdate(). + +It is not possible to change the signing parameters using these function. + +The previous two bugs are fixed in the newer EVP_SignDigest*() function. + +=head1 SEE ALSO + +L<EVP_VerifyInit(3)>, +L<EVP_DigestInit(3)>, +L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, +L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, +L<SHA1(3)>, L<dgst(1)> + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/EVP_VerifyInit.pod b/openssl-1.1.0h/doc/crypto/EVP_VerifyInit.pod new file mode 100644 index 0000000..9214609 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/EVP_VerifyInit.pod @@ -0,0 +1,94 @@ +=pod + +=head1 NAME + +EVP_VerifyInit_ex, +EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal +- EVP signature verification functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); + int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen, EVP_PKEY *pkey); + + int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); + +=head1 DESCRIPTION + +The EVP signature verification routines are a high level interface to digital +signatures. + +EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest +B<type> from ENGINE B<impl>. B<ctx> must be created by calling +EVP_MD_CTX_new() before calling this function. + +EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the +verification context B<ctx>. This function can be called several times on the +same B<ctx> to include additional data. + +EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey> +and against the B<siglen> bytes at B<sigbuf>. + +EVP_VerifyInit() initializes verification context B<ctx> to use the default +implementation of digest B<type>. + +=head1 RETURN VALUES + +EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for +failure. + +EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some +other error occurred. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 NOTES + +The B<EVP> interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +The call to EVP_VerifyFinal() internally finalizes a copy of the digest context. +This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called +later to digest and verify additional data. + +Since only a copy of the digest context is ever finalized the context must +be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak +will occur. + +=head1 BUGS + +Older versions of this documentation wrongly stated that calls to +EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal(). + +Since the public key is passed in the call to EVP_SignFinal() any error +relating to the private key (for example an unsuitable key and digest +combination) will not be indicated until after potentially large amounts of +data have been passed through EVP_SignUpdate(). + +It is not possible to change the signing parameters using these function. + +The previous two bugs are fixed in the newer EVP_VerifyDigest*() function. + +=head1 SEE ALSO + +L<evp(7)>, +L<EVP_SignInit(3)>, +L<EVP_DigestInit(3)>, +L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, +L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, +L<SHA1(3)>, L<dgst(1)> + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/HMAC.pod b/openssl-1.1.0h/doc/crypto/HMAC.pod new file mode 100644 index 0000000..219c9ba --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/HMAC.pod @@ -0,0 +1,152 @@ +=pod + +=head1 NAME + +HMAC, +HMAC_CTX_new, +HMAC_CTX_reset, +HMAC_CTX_free, +HMAC_Init, +HMAC_Init_ex, +HMAC_Update, +HMAC_Final, +HMAC_CTX_copy, +HMAC_CTX_set_flags, +HMAC_CTX_get_md +- HMAC message authentication code + +=head1 SYNOPSIS + + #include <openssl/hmac.h> + + unsigned char *HMAC(const EVP_MD *evp_md, const void *key, + int key_len, const unsigned char *d, int n, + unsigned char *md, unsigned int *md_len); + + HMAC_CTX *HMAC_CTX_new(void); + int HMAC_CTX_reset(HMAC_CTX *ctx); + + int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md, ENGINE *impl); + int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); + int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); + + void HMAC_CTX_free(HMAC_CTX *ctx); + + int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx); + void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags); + const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md); + #endif + +=head1 DESCRIPTION + +HMAC is a MAC (message authentication code), i.e. a keyed hash +function used for message authentication, which is based on a hash +function. + +HMAC() computes the message authentication code of the B<n> bytes at +B<d> using the hash function B<evp_md> and the key B<key> which is +B<key_len> bytes long. + +It places the result in B<md> (which must have space for the output of +the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes). +If B<md> is NULL, the digest is placed in a static array. The size of +the output is placed in B<md_len>, unless it is B<NULL>. Note: passing a NULL +value for B<md> to use the static array is not thread safe. + +B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. + +HMAC_CTX_new() creates a new HMAC_CTX in heap memory. + +HMAC_CTX_reset() zeroes an existing B<HMAC_CTX> and associated +resources, making it suitable for new computations as if it was newly +created with HMAC_CTX_new(). + +HMAC_CTX_free() erases the key and other data from the B<HMAC_CTX>, +releases any associated resources and finally frees the B<HMAC_CTX> +itself. + +The following functions may be used if the message is not completely +stored in memory: + +HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash +function B<evp_md> and the key B<key> which is B<key_len> bytes +long. It is deprecated and only included for backward compatibility +with OpenSSL 0.9.6b. + +HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash +function B<evp_md> and key B<key>. If both are NULL (or B<evp_md> is the same +as the previous digest used by B<ctx> and B<key> is NULL) the existing key is +reused. B<ctx> must have been created with HMAC_CTX_new() before the first use +of an B<HMAC_CTX> in this function. B<N.B. HMAC_Init() had this undocumented +behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex() +in programs that expect it will cause them to stop working>. + +B<NOTE:> If HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the +same as the previous digest used by B<ctx> then an error is returned +because reuse of an existing key with a different digest is not supported. + +HMAC_Update() can be called repeatedly with chunks of the message to +be authenticated (B<len> bytes at B<data>). + +HMAC_Final() places the message authentication code in B<md>, which +must have space for the hash function output. + +HMAC_CTX_copy() copies all of the internal state from B<sctx> into B<dctx>. + +HMAC_CTX_set_flags() applies the specified flags to the internal EVP_MD_CTXs. +These flags have the same meaning as for L<EVP_MD_CTX_set_flags(3)>. + +HMAC_CTX_get_md() returns the EVP_MD that has previously been set for the +supplied HMAC_CTX. + +=head1 RETURN VALUES + +HMAC() returns a pointer to the message authentication code or NULL if +an error occurred. + +HMAC_CTX_new() returns a pointer to a new B<HMAC_CTX> on success or +B<NULL> if an error occurred. + +HMAC_CTX_reset(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and +HMAC_CTX_copy() return 1 for success or 0 if an error occurred. + +HMAC_CTX_get_md() return the EVP_MD previously set for the supplied HMAC_CTX or +NULL if no EVP_MD has been set. + +=head1 CONFORMING TO + +RFC 2104 + +=head1 SEE ALSO + +L<sha(3)>, L<evp(3)> + +=head1 HISTORY + +HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL versions 1.1.0. + +HMAC_CTX_cleanup() existed in OpenSSL versions before 1.1.0. + +HMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL version +1.1.0. + +HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in +versions of OpenSSL before 1.0.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/MD5.pod b/openssl-1.1.0h/doc/crypto/MD5.pod new file mode 100644 index 0000000..78da750 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/MD5.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + +MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, +MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions + +=head1 SYNOPSIS + + #include <openssl/md2.h> + + unsigned char *MD2(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD2_Init(MD2_CTX *c); + int MD2_Update(MD2_CTX *c, const unsigned char *data, + unsigned long len); + int MD2_Final(unsigned char *md, MD2_CTX *c); + + + #include <openssl/md4.h> + + unsigned char *MD4(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD4_Init(MD4_CTX *c); + int MD4_Update(MD4_CTX *c, const void *data, + unsigned long len); + int MD4_Final(unsigned char *md, MD4_CTX *c); + + + #include <openssl/md5.h> + + unsigned char *MD5(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD5_Init(MD5_CTX *c); + int MD5_Update(MD5_CTX *c, const void *data, + unsigned long len); + int MD5_Final(unsigned char *md, MD5_CTX *c); + +=head1 DESCRIPTION + +MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. + +MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest +of the B<n> bytes at B<d> and place it in B<md> (which must have space +for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 +bytes of output). If B<md> is NULL, the digest is placed in a static +array. + +The following functions may be used if the message is not completely +stored in memory: + +MD2_Init() initializes a B<MD2_CTX> structure. + +MD2_Update() can be called repeatedly with chunks of the message to +be hashed (B<len> bytes at B<data>). + +MD2_Final() places the message digest in B<md>, which must have space +for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>. + +MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and +MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure. + +Applications should use the higher level functions +L<EVP_DigestInit(3)> +etc. instead of calling the hash functions directly. + +=head1 NOTE + +MD2, MD4, and MD5 are recommended only for compatibility with existing +applications. In new applications, SHA-1 or RIPEMD-160 should be +preferred. + +=head1 RETURN VALUES + +MD2(), MD4(), and MD5() return pointers to the hash value. + +MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), +MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for +success, 0 otherwise. + +=head1 CONFORMING TO + +RFC 1319, RFC 1320, RFC 1321 + +=head1 SEE ALSO + +L<EVP_DigestInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/MDC2_Init.pod b/openssl-1.1.0h/doc/crypto/MDC2_Init.pod new file mode 100644 index 0000000..f7db71b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/MDC2_Init.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +MDC2, MDC2_Init, MDC2_Update, MDC2_Final - MDC2 hash function + +=head1 SYNOPSIS + + #include <openssl/mdc2.h> + + unsigned char *MDC2(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MDC2_Init(MDC2_CTX *c); + int MDC2_Update(MDC2_CTX *c, const unsigned char *data, + unsigned long len); + int MDC2_Final(unsigned char *md, MDC2_CTX *c); + +=head1 DESCRIPTION + +MDC2 is a method to construct hash functions with 128 bit output from +block ciphers. These functions are an implementation of MDC2 with +DES. + +MDC2() computes the MDC2 message digest of the B<n> +bytes at B<d> and places it in B<md> (which must have space for +MDC2_DIGEST_LENGTH == 16 bytes of output). If B<md> is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +MDC2_Init() initializes a B<MDC2_CTX> structure. + +MDC2_Update() can be called repeatedly with chunks of the message to +be hashed (B<len> bytes at B<data>). + +MDC2_Final() places the message digest in B<md>, which must have space +for MDC2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MDC2_CTX>. + +Applications should use the higher level functions +L<EVP_DigestInit(3)> etc. instead of calling the +hash functions directly. + +=head1 RETURN VALUES + +MDC2() returns a pointer to the hash value. + +MDC2_Init(), MDC2_Update() and MDC2_Final() return 1 for success, 0 otherwise. + +=head1 CONFORMING TO + +ISO/IEC 10118-2, with DES + +=head1 SEE ALSO + +L<EVP_DigestInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OBJ_nid2obj.pod b/openssl-1.1.0h/doc/crypto/OBJ_nid2obj.pod new file mode 100644 index 0000000..3ada667 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OBJ_nid2obj.pod @@ -0,0 +1,198 @@ +=pod + +=head1 NAME + +i2t_ASN1_OBJECT, +OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln, +OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp, +OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup +- ASN1 object utility functions + +=head1 SYNOPSIS + + #include <openssl/objects.h> + + ASN1_OBJECT *OBJ_nid2obj(int n); + const char *OBJ_nid2ln(int n); + const char *OBJ_nid2sn(int n); + + int OBJ_obj2nid(const ASN1_OBJECT *o); + int OBJ_ln2nid(const char *ln); + int OBJ_sn2nid(const char *sn); + + int OBJ_txt2nid(const char *s); + + ASN1_OBJECT *OBJ_txt2obj(const char *s, int no_name); + int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name); + + int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a); + + int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b); + ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o); + + int OBJ_create(const char *oid, const char *sn, const char *ln); + + size_t OBJ_length(const ASN1_OBJECT *obj); + const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + void OBJ_cleanup(void) + #endif + +=head1 DESCRIPTION + +The ASN1 object utility functions process ASN1_OBJECT structures which are +a representation of the ASN1 OBJECT IDENTIFIER (OID) type. +For convenience, OIDs are usually represented in source code as numeric +identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that +are generated when the library is built, and their corresponding NIDs +are available as defined constants. For the functions below, application +code should treat all returned values -- OIDs, NIDs, or names -- as +constants. + +OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to +an ASN1_OBJECT structure, its long name and its short name respectively, +or B<NULL> is an error occurred. + +OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID +for the object B<o>, the long name <ln> or the short name <sn> respectively +or NID_undef if an error occurred. + +OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be +a long name, a short name or the numerical representation of an object. + +OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure. +If B<no_name> is 0 then long names and short names will be interpreted +as well as numerical forms. If B<no_name> is 1 only the numerical form +is acceptable. + +OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation. +The representation is written as a null terminated string to B<buf> +at most B<buf_len> bytes are written, truncating the result if necessary. +The total amount of space required is returned. If B<no_name> is 0 then +if the object has a long or short name then that will be used, otherwise +the numerical form will be used. If B<no_name> is 1 then the numerical +form will always be used. + +i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B<no_name> set to zero. + +OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned. + +OBJ_dup() returns a copy of B<o>. + +OBJ_create() adds a new object to the internal table. B<oid> is the +numerical form of the object, B<sn> the short name and B<ln> the +long name. A new NID is returned for the created object. + +OBJ_length() returns the size of the content octets of B<obj>. + +OBJ_get0_data() returns a pointer to the content octets of B<obj>. +The returned pointer is an internal pointer which B<must not> be freed. + +In OpenSSL versions prior to 1.1.0 OBJ_cleanup() cleaned up OpenSSLs internal +object table and was called before an application exits if any new objects were +added using OBJ_create(). This function is deprecated in version 1.1.0 and now +does nothing if called. No explicit de-initialisation is now required. See +L<OPENSSL_init_crypto(3)> for further information. + +=head1 NOTES + +Objects in OpenSSL can have a short name, a long name and a numerical +identifier (NID) associated with them. A standard set of objects is +represented in an internal table. The appropriate values are defined +in the header file B<objects.h>. + +For example the OID for commonName has the following definitions: + + #define SN_commonName "CN" + #define LN_commonName "commonName" + #define NID_commonName 13 + +New objects can be added by calling OBJ_create(). + +Table objects have certain advantages over other objects: for example +their NIDs can be used in a C language switch statement. They are +also static constant structures which are shared: that is there +is only a single constant structure for each table object. + +Objects which are not in the table have the NID value NID_undef. + +Objects do not need to be in the internal tables to be processed, +the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical +form of an OID. + +Some objects are used to represent algorithms which do not have a +corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently +exists for a particular algorithm). As a result they B<cannot> be encoded or +decoded as part of ASN.1 structures. Applications can determine if there +is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero. + +These functions cannot return B<const> because an B<ASN1_OBJECT> can +represent both an internal, constant, OID and a dynamically-created one. +The latter cannot be constant because it needs to be freed after use. + +=head1 EXAMPLES + +Create an object for B<commonName>: + + ASN1_OBJECT *o; + o = OBJ_nid2obj(NID_commonName); + +Check if an object is B<commonName> + + if (OBJ_obj2nid(obj) == NID_commonName) + /* Do something */ + +Create a new NID and initialize an object from it: + + int new_nid; + ASN1_OBJECT *obj; + + new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); + + obj = OBJ_nid2obj(new_nid); + +Create a new object directly: + + obj = OBJ_txt2obj("1.2.3.4", 1); + +=head1 BUGS + +OBJ_obj2txt() is awkward and messy to use: it doesn't follow the +convention of other OpenSSL functions where the buffer can be set +to B<NULL> to determine the amount of data that should be written. +Instead B<buf> must point to a valid buffer and B<buf_len> should +be set to a positive value. A buffer length of 80 should be more +than enough to handle any OID encountered in practice. + +=head1 RETURN VALUES + +OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an +error occurred. + +OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> +on error. + +OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return +a NID or B<NID_undef> on error. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 HISTORY + +OBJ_cleanup() was deprecated in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OCSP_REQUEST_new.pod b/openssl-1.1.0h/doc/crypto/OCSP_REQUEST_new.pod new file mode 100644 index 0000000..97c2337 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OCSP_REQUEST_new.pod @@ -0,0 +1,118 @@ +=pod + +=head1 NAME + +OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign, +OCSP_request_add1_cert, OCSP_request_onereq_count, +OCSP_request_onereq_get0 - OCSP request functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + OCSP_REQUEST *OCSP_REQUEST_new(void); + void OCSP_REQUEST_free(OCSP_REQUEST *req); + + OCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid); + + int OCSP_request_sign(OCSP_REQUEST *req, + X509 *signer, EVP_PKEY *key, const EVP_MD *dgst, + STACK_OF(X509) *certs, unsigned long flags); + + int OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert); + + int OCSP_request_onereq_count(OCSP_REQUEST *req); + OCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i); + +=head1 DESCRIPTION + +OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure. + +OCSP_REQUEST_free() frees up the request structure B<req>. + +OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns +the B<OCSP_ONEREQ> structure added so an application can add additional +extensions to the request. The B<id> parameter B<MUST NOT> be freed up after +the operation. + +OCSP_request_sign() signs OCSP request B<req> using certificate +B<signer>, private key B<key>, digest B<dgst> and additional certificates +B<certs>. If the B<flags> option B<OCSP_NOCERTS> is set then no certificates +will be included in the request. + +OCSP_request_add1_cert() adds certificate B<cert> to request B<req>. The +application is responsible for freeing up B<cert> after use. + +OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ> +structures in B<req>. + +OCSP_request_onereq_get0() returns an internal pointer to the B<OCSP_ONEREQ> +contained in B<req> of index B<i>. The index value B<i> runs from 0 to +OCSP_request_onereq_count(req) - 1. + +=head1 RETURN VALUES + +OCSP_REQUEST_new() returns an empty B<OCSP_REQUEST> structure or B<NULL> if +an error occurred. + +OCSP_request_add0_id() returns the B<OCSP_ONEREQ> structure containing B<cid> +or B<NULL> if an error occurred. + +OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0 +for failure. + +OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ> +structures in B<req>. + +OCSP_request_onereq_get0() returns a pointer to an B<OCSP_ONEREQ> structure +or B<NULL> if the index value is out or range. + +=head1 NOTES + +An OCSP request structure contains one or more B<OCSP_ONEREQ> structures +corresponding to each certificate. + +OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by +OCSP responders. + +=head1 EXAMPLE + +Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer +B<issuer>: + + OCSP_REQUEST *req; + OCSP_ID *cid; + + req = OCSP_REQUEST_new(); + if (req == NULL) + /* error */ + cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer); + if (cid == NULL) + /* error */ + + if (OCSP_REQUEST_add0_id(req, cid) == NULL) + /* error */ + + /* Do something with req, e.g. query responder */ + + OCSP_REQUEST_free(req); + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_cert_to_id(3)>, +L<OCSP_request_add1_nonce(3)>, +L<OCSP_response_find_status(3)>, +L<OCSP_response_status(3)>, +L<OCSP_sendreq_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OCSP_cert_to_id.pod b/openssl-1.1.0h/doc/crypto/OCSP_cert_to_id.pod new file mode 100644 index 0000000..0e37937 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OCSP_cert_to_id.pod @@ -0,0 +1,89 @@ +=pod + +=head1 NAME + +OCSP_cert_to_id, OCSP_cert_id_new, OCSP_CERTID_free, OCSP_id_issuer_cmp, +OCSP_id_cmp, OCSP_id_get0_info - OCSP certificate ID utility functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + OCSP_CERTID *OCSP_cert_to_id(const EVP_MD *dgst, + X509 *subject, X509 *issuer); + + OCSP_CERTID *OCSP_cert_id_new(const EVP_MD *dgst, + X509_NAME *issuerName, + ASN1_BIT_STRING *issuerKey, + ASN1_INTEGER *serialNumber); + + void OCSP_CERTID_free(OCSP_CERTID *id); + + int OCSP_id_issuer_cmp(OCSP_CERTID *a, OCSP_CERTID *b); + int OCSP_id_cmp(OCSP_CERTID *a, OCSP_CERTID *b); + + int OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd, + ASN1_OCTET_STRING **pikeyHash, + ASN1_INTEGER **pserial, OCSP_CERTID *cid); + + +=head1 DESCRIPTION + +OCSP_cert_to_id() creates and returns a new B<OCSP_CERTID> structure using +message digest B<dgst> for certificate B<subject> with issuer B<issuer>. If +B<dgst> is B<NULL> then SHA1 is used. + +OCSP_cert_id_new() creates and returns a new B<OCSP_CERTID> using B<dgst> and +issuer name B<issuerName>, issuer key hash B<issuerKey> and serial number +B<serialNumber>. + +OCSP_CERTID_free() frees up B<id>. + +OCSP_id_cmp() compares B<OCSP_CERTID> B<a> and B<b>. + +OCSP_id_issuer_cmp() compares only the issuer name of B<OCSP_CERTID> B<a> and B<b>. + +OCSP_id_get0_info() returns the issuer name hash, hash OID, issuer key hash and +serial number contained in B<cid>. If any of the values are not required the +corresponding parameter can be set to B<NULL>. + +=head1 RETURN VALUES + +OCSP_cert_to_id() and OCSP_cert_id_new() return either a pointer to a valid +B<OCSP_CERTID> structure or B<NULL> if an error occurred. + +OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and non-zero +otherwise. + +OCSP_CERTID_free() does not return a value. + +OCSP_id_get0_info() returns 1 for success and 0 for failure. + +=head1 NOTES + +OCSP clients will typically only use OCSP_cert_to_id() or OCSP_cert_id_new(): +the other functions are used by responder applications. + +The values returned by OCSP_id_get0_info() are internal pointers and B<MUST +NOT> be freed up by an application: they will be freed when the corresponding +B<OCSP_CERTID> structure is freed. + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_request_add1_nonce(3)>, +L<OCSP_REQUEST_new(3)>, +L<OCSP_response_find_status(3)>, +L<OCSP_response_status(3)>, +L<OCSP_sendreq_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OCSP_request_add1_nonce.pod b/openssl-1.1.0h/doc/crypto/OCSP_request_add1_nonce.pod new file mode 100644 index 0000000..dab42c6 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OCSP_request_add1_nonce.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +OCSP_request_add1_nonce, OCSP_basic_add1_nonce, OCSP_check_nonce, OCSP_copy_nonce - OCSP nonce functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + int OCSP_request_add1_nonce(OCSP_REQUEST *req, unsigned char *val, int len); + int OCSP_basic_add1_nonce(OCSP_BASICRESP *resp, unsigned char *val, int len); + int OCSP_copy_nonce(OCSP_BASICRESP *resp, OCSP_REQUEST *req); + int OCSP_check_nonce(OCSP_REQUEST *req, OCSP_BASICRESP *resp); + +=head1 DESCRIPTION + +OCSP_request_add1_nonce() adds a nonce of value B<val> and length B<len> to +OCSP request B<req>. If B<val> is B<NULL> a random nonce is used. If B<len> +is zero or negative a default length will be used (currently 16 bytes). + +OCSP_basic_add1_nonce() is identical to OCSP_request_add1_nonce() except +it adds a nonce to OCSP basic response B<resp>. + +OCSP_check_nonce() compares the nonce value in B<req> and B<resp>. + +OCSP_copy_nonce() copys any nonce value present in B<req> to B<resp>. + +=head1 RETURN VALUES + +OCSP_request_add1_nonce() and OCSP_basic_add1_nonce() return 1 for success +and 0 for failure. + +OCSP_copy_nonce() returns 1 if a nonce was successfully copied, 2 if no nonce +was present in B<req> and 0 if an error occurred. + +OCSP_check_nonce() returns the result of the nonce comparison between B<req> +and B<resp>. The return value indicates the result of the comparison. If +nonces are present and equal 1 is returned. If the nonces are absent 2 is +returned. If a nonce is present in the response only 3 is returned. If nonces +are present and unequal 0 is returned. If the nonce is present in the request +only then -1 is returned. + +=head1 NOTES + +For most purposes the nonce value in a request is set to a random value so +the B<val> parameter in OCSP_request_add1_nonce() is usually NULL. + +An OCSP nonce is typically added to an OCSP request to thwart replay attacks +by checking the same nonce value appears in the response. + +Some responders may include a nonce in all responses even if one is not +supplied. + +Some responders cache OCSP responses and do not sign each response for +performance reasons. As a result they do not support nonces. + +The return values of OCSP_check_nonce() can be checked to cover each case. A +positive return value effectively indicates success: nonces are both present +and match, both absent or present in the response only. A non-zero return +additionally covers the case where the nonce is present in the request only: +this will happen if the responder doesn't support nonces. A zero return value +indicates present and mismatched nonces: this should be treated as an error +condition. + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_cert_to_id(3)>, +L<OCSP_REQUEST_new(3)>, +L<OCSP_response_find_status(3)>, +L<OCSP_response_status(3)>, +L<OCSP_sendreq_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OCSP_resp_find_status.pod b/openssl-1.1.0h/doc/crypto/OCSP_resp_find_status.pod new file mode 100644 index 0000000..5123f0a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OCSP_resp_find_status.pod @@ -0,0 +1,152 @@ +=pod + +=head1 NAME + +OCSP_resp_get0_certs, +OCSP_resp_get0_signer, +OCSP_resp_get0_id, +OCSP_resp_get0_produced_at, +OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find, +OCSP_single_get0_status, OCSP_check_validity +- OCSP response utility functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status, + int *reason, + ASN1_GENERALIZEDTIME **revtime, + ASN1_GENERALIZEDTIME **thisupd, + ASN1_GENERALIZEDTIME **nextupd); + + int OCSP_resp_count(OCSP_BASICRESP *bs); + OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx); + int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last); + int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason, + ASN1_GENERALIZEDTIME **revtime, + ASN1_GENERALIZEDTIME **thisupd, + ASN1_GENERALIZEDTIME **nextupd); + + const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at( + const OCSP_BASICRESP* single); + + const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs); + + int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer, + STACK_OF(X509) *extra_certs); + + int OCSP_resp_get0_id(const OCSP_BASICRESP *bs, + const ASN1_OCTET_STRING **pid, + const X509_NAME **pname); + + int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd, + ASN1_GENERALIZEDTIME *nextupd, + long sec, long maxsec); + +=head1 DESCRIPTION + +OCSP_resp_find_status() searches B<bs> for an OCSP response for B<id>. If it is +successful the fields of the response are returned in B<*status>, B<*reason>, +B<*revtime>, B<*thisupd> and B<*nextupd>. The B<*status> value will be one of +B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or +B<V_OCSP_CERTSTATUS_UNKNOWN>. The B<*reason> and B<*revtime> fields are only +set if the status is B<V_OCSP_CERTSTATUS_REVOKED>. If set the B<*reason> field +will be set to the revocation reason which will be one of +B<OCSP_REVOKED_STATUS_NOSTATUS>, B<OCSP_REVOKED_STATUS_UNSPECIFIED>, +B<OCSP_REVOKED_STATUS_KEYCOMPROMISE>, B<OCSP_REVOKED_STATUS_CACOMPROMISE>, +B<OCSP_REVOKED_STATUS_AFFILIATIONCHANGED>, B<OCSP_REVOKED_STATUS_SUPERSEDED>, +B<OCSP_REVOKED_STATUS_CESSATIONOFOPERATION>, +B<OCSP_REVOKED_STATUS_CERTIFICATEHOLD> or B<OCSP_REVOKED_STATUS_REMOVEFROMCRL>. + +OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in B<bs>. + +OCSP_resp_get0() returns the B<OCSP_SINGLERESP> structure in B<bs> +corresponding to index B<idx>. Where B<idx> runs from 0 to +OCSP_resp_count(bs) - 1. + +OCSP_resp_find() searches B<bs> for B<id> and returns the index of the first +matching entry after B<last> or starting from the beginning if B<last> is -1. + +OCSP_single_get0_status() extracts the fields of B<single> in B<*reason>, +B<*revtime>, B<*thisupd> and B<*nextupd>. + +OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the +single response B<bs>. + +OCSP_resp_get0_certs() returns any certificates included in B<bs>. + +OCSP_resp_get0_signer() attempts to retrieve the certificate that directly +signed B<bs>. The OCSP protocol does not require that this certificate +is included in the B<certs> field of the response, so additional certificates +can be supplied in B<extra_certs> if the certificates that may have +signed the response are known via some out-of-band mechanism. + +OCSP_resp_get0_id() gets the responder id of B<bs>. If the responder ID is +a name then <*pname> is set to the name and B<*pid> is set to NULL. If the +responder ID is by key ID then B<*pid> is set to the key ID and B<*pname> +is set to NULL. + +OCSP_check_validity() checks the validity of B<thisupd> and B<nextupd> values +which will be typically obtained from OCSP_resp_find_status() or +OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds +leeway should be allowed in the check. If B<maxsec> is positive it indicates +the maximum age of B<thisupd> in seconds. + +=head1 RETURN VALUES + +OCSP_resp_find_status() returns 1 if B<id> is found in B<bs> and 0 otherwise. + +OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in +B<bs>. + +OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or +B<NULL> if B<idx> is out of range. + +OCSP_resp_find() returns the index of B<id> in B<bs> (which may be 0) or -1 if +B<id> was not found. + +OCSP_single_get0_status() returns the status of B<single> or -1 if an error +occurred. + +OCSP_resp_get0_signer() returns 1 if the signing certificate was located, +or 0 on error. + +=head1 NOTES + +Applications will typically call OCSP_resp_find_status() using the certificate +ID of interest and then check its validity using OCSP_check_validity(). They +can then take appropriate action based on the status of the certificate. + +An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate> +fields. Normally the current time should be between these two values. To +account for clock skew the B<maxsec> field can be set to non-zero in +OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this +would otherwise mean an ancient response would be considered valid: the +B<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted +age of responses. + +The values written to B<*revtime>, B<*thisupd> and B<*nextupd> by +OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers +which B<MUST NOT> be freed up by the calling application. Any or all of these +parameters can be set to NULL if their value is not required. + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_cert_to_id(3)>, +L<OCSP_request_add1_nonce(3)>, +L<OCSP_REQUEST_new(3)>, +L<OCSP_response_status(3)>, +L<OCSP_sendreq_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OCSP_response_status.pod b/openssl-1.1.0h/doc/crypto/OCSP_response_status.pod new file mode 100644 index 0000000..180ab8d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OCSP_response_status.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create, +OCSP_RESPONSE_free, OCSP_RESPID_set_by_name, +OCSP_RESPID_set_by_key, OCSP_RESPID_match - OCSP response functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + int OCSP_response_status(OCSP_RESPONSE *resp); + OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp); + OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs); + void OCSP_RESPONSE_free(OCSP_RESPONSE *resp); + + int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert); + int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert); + int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert); + +=head1 DESCRIPTION + +OCSP_response_status() returns the OCSP response status of B<resp>. It returns +one of the values: B<OCSP_RESPONSE_STATUS_SUCCESSFUL>, +B<OCSP_RESPONSE_STATUS_MALFORMEDREQUEST>, +B<OCSP_RESPONSE_STATUS_INTERNALERROR>, B<OCSP_RESPONSE_STATUS_TRYLATER> +B<OCSP_RESPONSE_STATUS_SIGREQUIRED>, or B<OCSP_RESPONSE_STATUS_UNAUTHORIZED>. + +OCSP_response_get1_basic() decodes and returns the B<OCSP_BASICRESP> structure +contained in B<resp>. + +OCSP_response_create() creates and returns an B<OCSP_RESPONSE> structure for +B<status> and optionally including basic response B<bs>. + +OCSP_RESPONSE_free() frees up OCSP response B<resp>. + +OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the +subject name in the supplied X509 certificate B<cert> for the OCSP responder. + +OCSP_RESPID_set_by_key() sets the key of the OCSP_RESPID to be the same as the +key in the supplied X509 certificate B<cert> for the OCSP responder. The key is +stored as a SHA1 hash. + +Note that an OCSP_RESPID can only have one of the name, or the key set. Calling +OCSP_RESPID_set_by_name() or OCSP_RESPID_set_by_key() will clear any existing +setting. + +OCSP_RESPID_match() tests whether the OCSP_RESPID given in B<respid> matches +with the X509 certificate B<cert>. + +=head1 RETURN VALUES + +OCSP_RESPONSE_status() returns a status value. + +OCSP_response_get1_basic() returns an B<OCSP_BASICRESP> structure pointer or +B<NULL> if an error occurred. + +OCSP_response_create() returns an B<OCSP_RESPONSE> structure pointer or B<NULL> +if an error occurred. + +OCSP_RESPONSE_free() does not return a value. + +OCSP_RESPID_set_by_name() and OCSP_RESPID_set_by_key() return 1 on success or 0 +on failure. + +OCSP_RESPID_match() returns 1 if the OCSP_RESPID and the X509 certificate match +or 0 otherwise. + +=head1 NOTES + +OCSP_response_get1_basic() is only called if the status of a response is +B<OCSP_RESPONSE_STATUS_SUCCESSFUL>. + +=head1 SEE ALSO + +L<crypto(3)> +L<OCSP_cert_to_id(3)> +L<OCSP_request_add1_nonce(3)> +L<OCSP_REQUEST_new(3)> +L<OCSP_response_find_status(3)> +L<OCSP_sendreq_new(3)> +L<OCSP_RESPID_new(3)> +L<OCSP_RESPID_free(3)> + +=head1 HISTORY + +The OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key() and OCSP_RESPID_match() +functions were added in OpenSSL 1.1.0a. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OCSP_sendreq_new.pod b/openssl-1.1.0h/doc/crypto/OCSP_sendreq_new.pod new file mode 100644 index 0000000..c7fdc9b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OCSP_sendreq_new.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +OCSP_sendreq_new, OCSP_sendreq_nbio, OCSP_REQ_CTX_free, +OCSP_set_max_response_length, OCSP_REQ_CTX_add1_header, +OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio - OCSP responder query functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req, + int maxline); + + int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx); + + void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx); + + void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len); + + int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx, + const char *name, const char *value); + + int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req); + + OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req, + int maxline); + +=head1 DESCRIPTION + +The function OCSP_sendreq_new() returns an B<OCSP_CTX> structure using the +responder B<io>, the URL path B<path>, the OCSP request B<req> and with a +response header maximum line length of B<maxline>. If B<maxline> is zero a +default value of 4k is used. The OCSP request B<req> may be set to B<NULL> +and provided later if required. + +OCSP_sendreq_nbio() performs non-blocking I/O on the OCSP request context +B<rctx>. When the operation is complete it returns the response in B<*presp>. + +OCSP_REQ_CTX_free() frees up the OCSP context B<rctx>. + +OCSP_set_max_response_length() sets the maximum response length for B<rctx> +to B<len>. If the response exceeds this length an error occurs. If not +set a default value of 100k is used. + +OCSP_REQ_CTX_add1_header() adds header B<name> with value B<value> to the +context B<rctx>. It can be called more than once to add multiple headers. +It B<MUST> be called before any calls to OCSP_sendreq_nbio(). The B<req> +parameter in the initial to OCSP_sendreq_new() call MUST be set to B<NULL> if +additional headers are set. + +OCSP_REQ_CTX_set1_req() sets the OCSP request in B<rctx> to B<req>. This +function should be called after any calls to OCSP_REQ_CTX_add1_header(). + +OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL +path B<path>, the OCSP request B<req> and with a response header maximum line +length of B<maxline>. If B<maxline> is zero a default value of 4k is used. + +=head1 RETURN VALUES + +OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL> if +an error occurred. + +OCSP_sendreq_nbio() returns B<1> if the operation was completed successfully, +B<-1> if the operation should be retried and B<0> if an error occurred. + +OCSP_REQ_CTX_add1_header() and OCSP_REQ_CTX_set1_req() return B<1> for success +and B<0> for failure. + +OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the +responder or B<NULL> if an error occurred. + +OCSP_REQ_CTX_free() and OCSP_set_max_response_length() do not return values. + +=head1 NOTES + +These functions only perform a minimal HTTP query to a responder. If an +application wishes to support more advanced features it should use an +alternative more complete HTTP library. + +Currently only HTTP POST queries to responders are supported. + +The arguments to OCSP_sendreq_new() correspond to the components of the URL. +For example if the responder URL is B<http://ocsp.com/ocspreq> the BIO +B<io> should be connected to host B<ocsp.com> on port 80 and B<path> +should be set to B<"/ocspreq"> + +The headers added with OCSP_REQ_CTX_add1_header() are of the form +"B<name>: B<value>" or just "B<name>" if B<value> is B<NULL>. So to add +a Host header for B<ocsp.com> you would call: + + OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com"); + +If OCSP_sendreq_nbio() indicates an operation should be retried the +corresponding BIO can be examined to determine which operation (read or +write) should be retried and appropriate action taken (for example a select() +call on the underlying socket). + +OCSP_sendreq_bio() does not support retries and so cannot handle non-blocking +I/O efficiently. It is retained for compatibility and its use in new +applications is not recommended. + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_cert_to_id(3)>, +L<OCSP_request_add1_nonce(3)>, +L<OCSP_REQUEST_new(3)>, +L<OCSP_response_find_status(3)>, +L<OCSP_response_status(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_Applink.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_Applink.pod new file mode 100644 index 0000000..d3a461b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_Applink.pod @@ -0,0 +1,31 @@ +=pod + +=head1 NAME + +OPENSSL_Applink - glue between OpenSSL BIO and Win32 compiler run-time + +=head1 SYNOPSIS + + __declspec(dllexport) void **OPENSSL_Applink(); + +=head1 DESCRIPTION + +OPENSSL_Applink is application-side interface which provides a glue +between OpenSSL BIO layer and Win32 compiler run-time environment. +Even though it appears at application side, it's essentially OpenSSL +private interface. For this reason application developers are not +expected to implement it, but to compile provided module with +compiler of their choice and link it into the target application. +The referred module is available as F<applink.c>, located alongside +the public header files (only on the platforms where applicable). + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_LH_COMPFUNC.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_LH_COMPFUNC.pod new file mode 100644 index 0000000..e760ae3 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_LH_COMPFUNC.pod @@ -0,0 +1,239 @@ +=pod + +=head1 NAME + +DECLARE_LHASH_OF, +OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC, +LHASH_DOALL_ARG_FN_TYPE, +IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN, +lh_TYPE_new, lh_TYPE_free, +lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, +lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/lhash.h> + + DECLARE_LHASH_OF(TYPE); + + LHASH *lh_TYPE_new(); + void lh_TYPE_free(LHASH_OF(TYPE *table); + + TYPE *lh_TYPE_insert(LHASH_OF(TYPE *table, TYPE *data); + TYPE *lh_TYPE_delete(LHASH_OF(TYPE *table, TYPE *data); + TYPE *lh_retrieve(LHASH_OFTYPE *table, TYPE *data); + + void lh_TYPE_doall(LHASH_OF(TYPE *table, OPENSSL_LH_DOALL_FUNC func); + void lh_TYPE_doall_arg(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNCARG func, + TYPE, TYPE *arg); + + int lh_TYPE_error(LHASH_OF(TYPE) *table); + + typedef int (*OPENSSL_LH_COMPFUNC)(const void *, const void *); + typedef unsigned long (*OPENSSL_LH_HASHFUNC)(const void *); + typedef void (*OPENSSL_LH_DOALL_FUNC)(const void *); + typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); + +=head1 DESCRIPTION + +This library implements type-checked dynamic hash tables. The hash +table entries can be arbitrary structures. Usually they consist of key +and value fields. In the description here, I<TYPE> is used a placeholder +for any of the OpenSSL datatypes, such as I<SSL_SESSION>. + +lh_TYPE_new() creates a new B<LHASH_OF(TYPE)> structure to store +arbitrary data entries, and specifies the 'hash' and 'compare' +callbacks to be used in organising the table's entries. The B<hash> +callback takes a pointer to a table entry as its argument and returns +an unsigned long hash value for its key field. The hash value is +normally truncated to a power of 2, so make sure that your hash +function returns well mixed low order bits. The B<compare> callback +takes two arguments (pointers to two hash table entries), and returns +0 if their keys are equal, non-zero otherwise. + +If your hash table +will contain items of some particular type and the B<hash> and +B<compare> callbacks hash/compare these types, then the +B<IMPLEMENT_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be +used to create callback wrappers of the prototypes required by +lh_TYPE_new() as shown in this example: + + /* + * Implement the hash and compare functions; "stuff" can be any word. + */ + static unsigned long stuff_hash(const TYPE *a) + { + ... + } + static int stuff_cmp(const TYPE *a, const TYPE *b) + { + ... + } + + /* + * Implement the wrapper functions. + */ + static IMPLEMENT_LHASH_HASH_FN(stuff, TYPE) + static IMPLEMENT_LHASH_COMP_FN(stuff, TYPE) + +If the type is going to be used in several places, the following macros +can be used in a common header file to declare the function wrappers: + + DECLARE_LHASH_HASH_FN(stuff, TYPE) + DECLARE_LHASH_COMP_FN(stuff, TYPE) + +Then a hash table of TYPE objects can be created using this: + + LHASH_OF(TYPE) *htable; + + htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff)); + +lh_TYPE_free() frees the B<LHASH_OF(TYPE)> structure +B<table>. Allocated hash table entries will not be freed; consider +using lh_TYPE_doall() to deallocate any remaining entries in the +hash table (see below). + +lh_TYPE_insert() inserts the structure pointed to by B<data> into +B<table>. If there already is an entry with the same key, the old +value is replaced. Note that lh_TYPE_insert() stores pointers, the +data are not copied. + +lh_TYPE_delete() deletes an entry from B<table>. + +lh_TYPE_retrieve() looks up an entry in B<table>. Normally, B<data> +is a structure with the key field(s) set; the function will return a +pointer to a fully populated structure. + +lh_TYPE_doall() will, for every entry in the hash table, call +B<func> with the data item as its parameter. +For example: + + /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ + void TYPE_cleanup_doall(TYPE *a); + + /* Implement a prototype-compatible wrapper for "TYPE_cleanup" */ + IMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE) + + /* Call "TYPE_cleanup" against all items in a hash table. */ + lh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup)); + + /* Then the hash table itself can be deallocated */ + lh_TYPE_free(hashtable); + +When doing this, be careful if you delete entries from the hash table +in your callbacks: the table may decrease in size, moving the item +that you are currently on down lower in the hash table - this could +cause some entries to be skipped during the iteration. The second +best solution to this problem is to set hash-E<gt>down_load=0 before +you start (which will stop the hash table ever decreasing in size). +The best solution is probably to avoid deleting items from the hash +table inside a "doall" callback! + +lh_TYPE_doall_arg() is the same as lh_TYPE_doall() except that +B<func> will be called with B<arg> as the second argument and B<func> +should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype +that is passed both the table entry and an extra argument). As with +lh_doall(), you can instead choose to declare your callback with a +prototype matching the types you are dealing with and use the +declare/implement macros to create compatible wrappers that cast +variables before calling your type-specific callbacks. An example of +this is demonstrated here (printing all hash table entries to a BIO +that is provided by the caller): + + /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ + void TYPE_print_doall_arg(const TYPE *a, BIO *output_bio); + + /* Implement a prototype-compatible wrapper for "TYPE_print" */ + static IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO) + + /* Print out the entire hashtable to a particular BIO */ + lh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO, + logging_bio); + + +lh_TYPE_error() can be used to determine if an error occurred in the last +operation. + +=head1 RETURN VALUES + +lh_TYPE_new() returns B<NULL> on error, otherwise a pointer to the new +B<LHASH> structure. + +When a hash table entry is replaced, lh_TYPE_insert() returns the value +being replaced. B<NULL> is returned on normal operation and on error. + +lh_TYPE_delete() returns the entry being deleted. B<NULL> is returned if +there is no such value in the hash table. + +lh_TYPE_retrieve() returns the hash table entry if it has been found, +B<NULL> otherwise. + +lh_TYPE_error() returns 1 if an error occurred in the last operation, 0 +otherwise. + +lh_TYPE_free(), lh_TYPE_doall() and lh_TYPE_doall_arg() return no values. + +=head1 NOTE + +The various LHASH macros and callback types exist to make it possible +to write type-checked code without resorting to function-prototype +casting - an evil that makes application code much harder to +audit/verify and also opens the window of opportunity for stack +corruption and other hard-to-find bugs. It also, apparently, violates +ANSI-C. + +The LHASH code regards table entries as constant data. As such, it +internally represents lh_insert()'d items with a "const void *" +pointer type. This is why callbacks such as those used by lh_doall() +and lh_doall_arg() declare their prototypes with "const", even for the +parameters that pass back the table items' data pointers - for +consistency, user-provided data is "const" at all times as far as the +LHASH code is concerned. However, as callers are themselves providing +these pointers, they can choose whether they too should be treating +all such parameters as constant. + +As an example, a hash table may be maintained by code that, for +reasons of encapsulation, has only "const" access to the data being +indexed in the hash table (ie. it is returned as "const" from +elsewhere in their code) - in this case the LHASH prototypes are +appropriate as-is. Conversely, if the caller is responsible for the +life-time of the data in question, then they may well wish to make +modifications to table item passed back in the lh_doall() or +lh_doall_arg() callbacks (see the "TYPE_cleanup" example above). If +so, the caller can either cast the "const" away (if they're providing +the raw callbacks themselves) or use the macros to declare/implement +the wrapper functions without "const" types. + +Callers that only have "const" access to data they're indexing in a +table, yet declare callbacks without constant types (or cast the +"const" away themselves), are therefore creating their own risks/bugs +without being encouraged to do so by the API. On a related note, +those auditing code should pay special attention to any instances of +DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types +without any "const" qualifiers. + +=head1 BUGS + +lh_TYPE_insert() returns B<NULL> both for success and error. + +=head1 SEE ALSO + +L<lh_stats(3)> + +=head1 HISTORY + +In OpenSSL 1.0.0, the lhash interface was revamped for better +type checking. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_LH_stats.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_LH_stats.pod new file mode 100644 index 0000000..c454a47 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_LH_stats.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +OPENSSL_LH_stats, OPENSSL_LH_node_stats, OPENSSL_LH_node_usage_stats, +OPENSSL_LH_stats_bio, +OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio - LHASH statistics + +=head1 SYNOPSIS + + #include <openssl/lhash.h> + + void OPENSSL_LH_stats(LHASH *table, FILE *out); + void OPENSSL_LH_node_stats(LHASH *table, FILE *out); + void OPENSSL_LH_node_usage_stats(LHASH *table, FILE *out); + + void OPENSSL_LH_stats_bio(LHASH *table, BIO *out); + void OPENSSL_LH_node_stats_bio(LHASH *table, BIO *out); + void OPENSSL_LH_node_usage_stats_bio(LHASH *table, BIO *out); + +=head1 DESCRIPTION + +The B<LHASH> structure records statistics about most aspects of +accessing the hash table. This is mostly a legacy of Eric Young +writing this library for the reasons of implementing what looked like +a nice algorithm rather than for a particular software product. + +OPENSSL_LH_stats() prints out statistics on the size of the hash table, how +many entries are in it, and the number and result of calls to the +routines in this library. + +OPENSSL_LH_node_stats() prints the number of entries for each 'bucket' in the +hash table. + +OPENSSL_LH_node_usage_stats() prints out a short summary of the state of the +hash table. It prints the 'load' and the 'actual load'. The load is +the average number of data items per 'bucket' in the hash table. The +'actual load' is the average number of items per 'bucket', but only +for buckets which contain entries. So the 'actual load' is the +average number of searches that will need to find an item in the hash +table, while the 'load' is the average number that will be done to +record a miss. + +OPENSSL_LH_stats_bio(), OPENSSL_LH_node_stats_bio() and OPENSSL_LH_node_usage_stats_bio() +are the same as the above, except that the output goes to a B<BIO>. + +=head1 RETURN VALUES + +These functions do not return values. + +=head1 SEE ALSO + +L<bio(3)>, L<lhash(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_VERSION_NUMBER.pod new file mode 100644 index 0000000..f50faec --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_VERSION_NUMBER.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +OPENSSL_VERSION_NUMBER, OpenSSL_version, +OpenSSL_version_num - get OpenSSL version number + +=head1 SYNOPSIS + + #include <openssl/opensslv.h> + #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL + + #include <openssl/crypto.h> + + unsigned long OpenSSL_version_num(); + const char *OpenSSL_version(int t); + +=head1 DESCRIPTION + +OPENSSL_VERSION_NUMBER is a numeric release version identifier: + + MNNFFPPS: major minor fix patch status + +The status nibble has one of the values 0 for development, 1 to e for betas +1 to 14, and f for release. + +for example + + 0x000906000 == 0.9.6 dev + 0x000906023 == 0.9.6b beta 3 + 0x00090605f == 0.9.6e release + +Versions prior to 0.9.3 have identifiers E<lt> 0x0930. +Versions between 0.9.3 and 0.9.5 had a version identifier with this +interpretation: + + MMNNFFRBB major minor fix final beta/patch + +for example + + 0x000904100 == 0.9.4 release + 0x000905000 == 0.9.5 dev + +Version 0.9.5a had an interim interpretation that is like the current one, +except the patch level got the highest bit set, to keep continuity. The +number was therefore 0x0090581f. + +OpenSSL_version_num() returns the version number. + +The macro OPENSSL_VERSION_AT_LEAST(major,minor) can be used at compile +time test if the current version is at least as new as the version provided. +The arguments major, minor and fix correspond to the version information +as given above. + +OpenSSL_version() returns different strings depending on B<t>: + +=over 4 + +=item OPENSSL_VERSION + +The text variant of the version number and the release date. For example, +"OpenSSL 1.0.1a 15 Oct 2015". + +=item OPENSSL_CFLAGS + +The compiler flags set for the compilation process in the form +"compiler: ..." if available or "compiler: information not available" +otherwise. + +=item OPENSSL_BUILT_ON + +The date of the build process in the form "built on: ..." if available +or "built on: date not available" otherwise. + +=item OPENSSL_PLATFORM + +The "Configure" target of the library build in the form "platform: ..." +if available or "platform: information not available" otherwise. + +=item OPENSSL_DIR + +The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "..."" +if available or "OPENSSLDIR: N/A" otherwise. + +=item OPENSSL_ENGINES_DIR + +The "ENGINESDIR" setting of the library build in the form "ENGINESDIR: "..."" +if available or "ENGINESDIR: N/A" otherwise. + +=back + +For an unknown B<t>, the text "not available" is returned. + +=head1 RETURN VALUE + +The version number. + +=head1 SEE ALSO + +L<crypto(3)> + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_config.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_config.pod new file mode 100644 index 0000000..eae634a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_config.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions + +=head1 SYNOPSIS + + #include <openssl/conf.h> + + #if OPENSSL_API_COMPAT < 0x10100000L + void OPENSSL_config(const char *appname); + void OPENSSL_no_config(void); + #endif + +=head1 DESCRIPTION + +OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> and +reads from the application section B<appname>. If B<appname> is NULL then +the default section, B<openssl_conf>, will be used. +Errors are silently ignored. +Multiple calls have no effect. + +OPENSSL_no_config() disables configuration. If called before OPENSSL_config() +no configuration takes place. + +If the application is built with B<OPENSSL_LOAD_CONF> defined, then a +call to OpenSSL_add_all_algorithms() will implicitly call OPENSSL_config() +first. + +=head1 NOTES + +The OPENSSL_config() function is designed to be a very simple "call it and +forget it" function. +It is however B<much> better than nothing. Applications which need finer +control over their configuration functionality should use the configuration +functions such as CONF_modules_load() directly. This function is deprecated +and its use should be avoided. +Applications should instead call CONF_modules_load() during +initialization (that is before starting any threads). + +There are several reasons why calling the OpenSSL configuration routines is +advisable. For example, to load dynamic ENGINEs from shared libraries (DSOs). +However very few applications currently support the control interface and so +very few can load and use dynamic ENGINEs. Equally in future more sophisticated +ENGINEs will require certain control operations to customize them. If an +application calls OPENSSL_config() it doesn't need to know or care about +ENGINE control operations because they can be performed by editing a +configuration file. + +=head1 RETURN VALUES + +Neither OPENSSL_config() nor OPENSSL_no_config() return a value. + +=head1 SEE ALSO + +L<conf(5)>, +L<CONF_modules_load_file(3)> + +=head1 HISTORY + +The OPENSSL_no_config() and OPENSSL_config() functions were +deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto(). + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_ia32cap.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_ia32cap.pod new file mode 100644 index 0000000..b0ab0ce --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_ia32cap.pod @@ -0,0 +1,140 @@ +=pod + +=head1 NAME + +OPENSSL_ia32cap - the x86[_64] processor capabilities vector + +=head1 SYNOPSIS + + env OPENSSL_ia32cap=... <application> + +=head1 DESCRIPTION + +OpenSSL supports a range of x86[_64] instruction set extensions. These +extensions are denoted by individual bits in capability vector returned +by processor in EDX:ECX register pair after executing CPUID instruction +with EAX=1 input value (see Intel Application Note #241618). This vector +is copied to memory upon toolkit initialization and used to choose +between different code paths to provide optimal performance across wide +range of processors. For the moment of this writing following bits are +significant: + +=over 4 + +=item bit #4 denoting presence of Time-Stamp Counter. + +=item bit #19 denoting availability of CLFLUSH instruction; + +=item bit #20, reserved by Intel, is used to choose among RC4 code paths; + +=item bit #23 denoting MMX support; + +=item bit #24, FXSR bit, denoting availability of XMM registers; + +=item bit #25 denoting SSE support; + +=item bit #26 denoting SSE2 support; + +=item bit #28 denoting Hyperthreading, which is used to distinguish +cores with shared cache; + +=item bit #30, reserved by Intel, denotes specifically Intel CPUs; + +=item bit #33 denoting availability of PCLMULQDQ instruction; + +=item bit #41 denoting SSSE3, Supplemental SSE3, support; + +=item bit #43 denoting AMD XOP support (forced to zero on non-AMD CPUs); + +=item bit #54 denoting availability of MOVBE instruction; + +=item bit #57 denoting AES-NI instruction set extension; + +=item bit #58, XSAVE bit, lack of which in combination with MOVBE is used +to identify Atom Silvermont core; + +=item bit #59, OSXSAVE bit, denoting availability of YMM registers; + +=item bit #60 denoting AVX extension; + +=item bit #62 denoting availability of RDRAND instruction; + +=back + +For example, in 32-bit application context clearing bit #26 at run-time +disables high-performance SSE2 code present in the crypto library, while +clearing bit #24 disables SSE2 code operating on 128-bit XMM register +bank. You might have to do the latter if target OpenSSL application is +executed on SSE2 capable CPU, but under control of OS that does not +enable XMM registers. Historically address of the capability vector copy +was exposed to application through OPENSSL_ia32cap_loc(), but not +anymore. Now the only way to affect the capability detection is to set +OPENSSL_ia32cap environment variable prior target application start. To +give a specific example, on Intel P4 processor 'env +OPENSSL_ia32cap=0x16980010 apps/openssl', or better yet 'env +OPENSSL_ia32cap=~0x1000000 apps/openssl' would achieve the desired +effect. Alternatively you can reconfigure the toolkit with no-sse2 +option and recompile. + +Less intuitive is clearing bit #28, or ~0x10000000 in the "environment +variable" terms. The truth is that it's not copied from CPUID output +verbatim, but is adjusted to reflect whether or not the data cache is +actually shared between logical cores. This in turn affects the decision +on whether or not expensive countermeasures against cache-timing attacks +are applied, most notably in AES assembler module. + +The capability vector is further extended with EBX value returned by +CPUID with EAX=7 and ECX=0 as input. Following bits are significant: + +=over 4 + +=item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN; + +=item bit #64+5 denoting availability of AVX2 instructions; + +=item bit #64+8 denoting availability of BMI2 instructions, e.g. MULX +and RORX; + +=item bit #64+16 denoting availability of AVX512F extension; + +=item bit #64+18 denoting availability of RDSEED instruction; + +=item bit #64+19 denoting availability of ADCX and ADOX instructions; + +=item bit #64+29 denoting availability of SHA extension; + +=item bit #64+30 denoting availability of AVX512BW extension; + +=item bit #64+31 denoting availability of AVX512VL extension; + +=back + +To control this extended capability word use ':' as delimiter when +setting up OPENSSL_ia32cap environment variable. For example assigning +':~0x20' would disable AVX2 code paths, and ':0' - all post-AVX +extensions. + +It should be noted that whether or not some of the most "fancy" +extension code paths are actually assembled depends on current assembler +version. Base minimum of AES-NI/PCLMULQDQ, SSSE3 and SHA extension code +paths are always assembled. Besides that, minimum assembler version +requirements are summarized in below table: + + Extension | GNU as | nasm | llvm + ------------+--------+--------+-------- + AVX | 2.19 | 2.09 | 3.0 + AVX2 | 2.22 | 2.10 | 3.1 + AVX512 | 2.25 | 2.11.8 | 3.6 + +B<OPENSSL_ia32cap> is a macro returning the first word of the vector. + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_init_crypto.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_init_crypto.pod new file mode 100644 index 0000000..f0b3c8a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_init_crypto.pod @@ -0,0 +1,245 @@ +=pod + +=head1 NAME + +OPENSSL_init_new, OPENSSL_INIT_set_config_appname, OPENSSL_INIT_free, +OPENSSL_init_crypto, OPENSSL_cleanup, +OPENSSL_atexit, OPENSSL_thread_stop - OpenSSL +initialisation and deinitialisation functions + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + void OPENSSL_cleanup(void); + int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); + int OPENSSL_atexit(void (*handler)(void)); + void OPENSSL_thread_stop(void); + + OPENSSL_INIT_SETTINGS *OPENSSL_init_new(void); + int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init, + const char* name); + void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init); + +=head1 DESCRIPTION + +During normal operation OpenSSL (libcrypto) will allocate various resources at +start up that must, subsequently, be freed on close down of the library. +Additionally some resources are allocated on a per thread basis (if the +application is multi-threaded), and these resources must be freed prior to the +thread closing. + +As of version 1.1.0 OpenSSL will automatically allocate all resources that it +needs so no explicit initialisation is required. Similarly it will also +automatically deinitialise as required. + +However, there way be situations when explicit initialisation is desirable or +needed, for example when some non-default initialisation is required. The +function OPENSSL_init_crypto() can be used for this purpose for +libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl +equivalent). + +Numerous internal OpenSSL functions call OPENSSL_init_crypto(). +Therefore, in order to perform non-default initialisation, +OPENSSL_init_crypto() MUST be called by application code prior to +any other OpenSSL function calls. + +The B<opts> parameter specifies which aspects of libcrypto should be +initialised. Valid options are: + +=over 4 + +=item OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS + +Suppress automatic loading of the libcrypto error strings. This option is +not a default option. Once selected subsequent calls to +OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored. + +=item OPENSSL_INIT_LOAD_CRYPTO_STRINGS + +Automatic loading of the libcrypto error strings. With this option the +library will automatically load the libcrypto error strings. +This option is a default option. Once selected subsequent calls to +OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS> will be ignored. + +=item OPENSSL_INIT_ADD_ALL_CIPHERS + +With this option the library will automatically load and make available all +libcrypto ciphers. This option is a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored. + +=item OPENSSL_INIT_ADD_ALL_DIGESTS + +With this option the library will automatically load and make available all +libcrypto digests. This option is a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored. + +=item OPENSSL_INIT_NO_ADD_ALL_CIPHERS + +With this option the library will suppress automatic loading of libcrypto +ciphers. This option is not a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_ADD_ALL_CIPHERS> will be ignored. + +=item OPENSSL_INIT_NO_ADD_ALL_DIGESTS + +With this option the library will suppress automatic loading of libcrypto +digests. This option is not a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_ADD_ALL_DIGESTS> will be ignored. + +=item OPENSSL_INIT_LOAD_CONFIG + +With this option an OpenSSL configuration file will be automatically loaded and +used by calling OPENSSL_config(). This is not a default option. +See the description of OPENSSL_init_new(), below. + +=item OPENSSL_INIT_NO_LOAD_CONFIG + +With this option the loading of OpenSSL configuration files will be suppressed. +It is the equivalent of calling OPENSSL_no_config(). This is not a default +option. + +=item OPENSSL_INIT_ASYNC + +With this option the library with automatically initialise the libcrypto async +sub-library (see L<ASYNC_start_job(3)>). This is a default option. + +=item OPENSSL_INIT_ENGINE_RDRAND + +With this option the library will automatically load and initialise the +RDRAND engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_DYNAMIC + +With this option the library will automatically load and initialise the +dynamic engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_OPENSSL + +With this option the library will automatically load and initialise the +openssl engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_CRYPTODEV + +With this option the library will automatically load and initialise the +cryptodev engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_CAPI + +With this option the library will automatically load and initialise the +CAPI engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_PADLOCK + +With this option the library will automatically load and initialise the +padlock engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_DASYNC + +With this option the library will automatically load and initialise the +DASYNC engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_ALL_BUILTIN + +With this option the library will automatically load and initialise all the +built in engines listed above with the exception of the openssl and dasync +engines. This not a default option. + +=back + +Multiple options may be combined together in a single call to +OPENSSL_init_crypto(). For example: + + OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS + | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL); + +The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto +and libssl). All resources allocated by OpenSSL are freed. Typically there +should be no need to call this function directly as it is initiated +automatically on application exit. This is done via the standard C library +atexit() function. In the event that the application will close in a manner +that will not call the registered atexit() handlers then the application should +call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL +are discouraged from calling this function and should instead, typically, rely +on auto-deinitialisation. This is to avoid error conditions where both an +application and a library it depends on both use OpenSSL, and the library +deinitialises it before the application has finished using it. + +Once OPENSSL_cleanup() has been called the library cannot be reinitialised. +Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error +will be added to the error stack. Note that because initialisation has failed +OpenSSL error strings will not be available, only an error code. This code can +be put through the openssl errstr command line application to produce a human +readable error (see L<errstr(1)>). + +The OPENSSL_atexit() function enables the registration of a +function to be called during OPENSSL_cleanup(). Stop handlers are +called after deinitialisation of resources local to a thread, but before other +process wide resources are freed. In the event that multiple stop handlers are +registered, no guarantees are made about the order of execution. + +The OPENSSL_thread_stop() function deallocates resources associated +with the current thread. Typically this function will be called automatically by +the library when the thread exits. This should only be called directly if +resources should be freed at an earlier time, or under the circumstances +described in the NOTES section below. + +The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a default configuration +file. To specify a different file, an B<OPENSSL_INIT_SETTINGS> must +be created and used. The routines +OPENSSL_init_new() and OPENSSL_INIT_set_config_appname() can be used to +allocate the object and set the application name, and then the +object can be released with OPENSSL_INIT_free() when done. + +=head1 NOTES + +Resources local to a thread are deallocated automatically when the thread exits +(e.g. in a pthreads environment, when pthread_exit() is called). On Windows +platforms this is done in response to a DLL_THREAD_DETACH message being sent to +the libcrypto32.dll entry point. Some windows functions may cause threads to exit +without sending this message (for example ExitProcess()). If the application +uses such functions, then the application must free up OpenSSL resources +directly via a call to OPENSSL_thread_stop() on each thread. Similarly this +message will also not be sent if OpenSSL is linked statically, and therefore +applications using static linking should also call OPENSSL_thread_stop() on each +thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the +threads are not destroyed until after FreeLibrary() is called then each thread +should call OPENSSL_thread_stop() prior to the FreeLibrary() call. + +On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is +multi-threaded and if dlclose() is subsequently called prior to the threads +being destroyed then OpenSSL will not be able to deallocate resources associated +with those threads. The application should either call OPENSSL_thread_stop() on +each thread prior to the dlclose() call, or alternatively the original dlopen() +call should use the RTLD_NODELETE flag (where available on the platform). + +=head1 RETURN VALUES + +The functions OPENSSL_init_crypto, OPENSSL_atexit() and +OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error. + +=head1 SEE ALSO + +L<OPENSSL_init_ssl(3)> + +=head1 HISTORY + +The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(), +OPENSSL_thread_stop(), OPENSSL_init_new(), OPENSSL_INIT_set_config_appname() +and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_instrument_bus.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_instrument_bus.pod new file mode 100644 index 0000000..1407261 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_instrument_bus.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memory bus + +=head1 SYNOPSIS + + #ifdef OPENSSL_CPUID_OBJ + size_t OPENSSL_instrument_bus(int *vector, size_t num); + size_t OPENSSL_instrument_bus2(int *vector, size_t num, size_t max); + #endif + +=head1 DESCRIPTION + +It was empirically found that timings of references to primary memory +are subject to irregular, apparently non-deterministic variations. The +subroutines in question instrument these references for purposes of +gathering entropy for random number generator. In order to make it +bus-bound a 'flush cache line' instruction is used between probes. In +addition probes are added to B<vector> elements in atomic or +interlocked manner, which should contribute additional noise on +multi-processor systems. This also means that B<vector[num]> should be +zeroed upon invocation (if you want to retrieve actual probe values). + +OPENSSL_instrument_bus() performs B<num> probes and records the number of +oscillator cycles every probe took. + +OPENSSL_instrument_bus2() on the other hand B<accumulates> consecutive +probes with the same value, i.e. in a way it records duration of +periods when probe values appeared deterministic. The subroutine +performs at most B<max> probes in attempt to fill the B<vector[num]>, +with B<max> value of 0 meaning "as many as it takes." + +=head1 RETURN VALUE + +Return value of 0 indicates that CPU is not capable of performing the +benchmark, either because oscillator counter or 'flush cache line' is +not available on current platform. For reference, on x86 'flush cache +line' was introduced with the SSE2 extensions. + +Otherwise number of recorded values is returned. + +=head1 COPYRIGHT + +Copyright 2011-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_load_builtin_modules.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_load_builtin_modules.pod new file mode 100644 index 0000000..112718a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_load_builtin_modules.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules + +=head1 SYNOPSIS + + #include <openssl/conf.h> + + void OPENSSL_load_builtin_modules(void); + void ASN1_add_oid_module(void); + ENGINE_add_conf_module(); + +=head1 DESCRIPTION + +The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL +configuration modules to the internal list. They can then be used by the +OpenSSL configuration code. + +ASN1_add_oid_module() adds just the ASN1 OBJECT module. + +ENGINE_add_conf_module() adds just the ENGINE configuration module. + +=head1 NOTES + +If the simple configuration function OPENSSL_config() is called then +OPENSSL_load_builtin_modules() is called automatically. + +Applications which use the configuration functions directly will need to +call OPENSSL_load_builtin_modules() themselves I<before> any other +configuration code. + +Applications should call OPENSSL_load_builtin_modules() to load all +configuration modules instead of adding modules selectively: otherwise +functionality may be missing from the application if an when new +modules are added. + +=head1 RETURN VALUE + +None of the functions return a value. + +=head1 SEE ALSO + +L<conf(3)>, L<OPENSSL_config(3)> + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod new file mode 100644 index 0000000..2104f43 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_malloc.pod @@ -0,0 +1,207 @@ +=pod + +=head1 NAME + +OPENSSL_malloc_init, +OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free, +OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse, +CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free, +OPENSSL_strdup, OPENSSL_strndup, +OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, +OPENSSL_hexstr2buf, OPENSSL_buf2hexstr, OPENSSL_hexchar2int, +CRYPTO_strdup, CRYPTO_strndup, +OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, +CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, +CRYPTO_clear_realloc, CRYPTO_clear_free, +CRYPTO_get_mem_functions, CRYPTO_set_mem_functions, +CRYPTO_set_mem_debug, CRYPTO_mem_ctrl, +CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + int OPENSSL_malloc_init(void) + + void *OPENSSL_malloc(size_t num) + void *OPENSSL_zalloc(size_t num) + void *OPENSSL_realloc(void *addr, size_t num) + void OPENSSL_free(void *addr) + char *OPENSSL_strdup(const char *str) + char *OPENSSL_strndup(const char *str, size_t s) + size_t OPENSSL_strlcat(char *dst, const char *src, size_t size); + size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size); + void *OPENSSL_memdup(void *data, size_t s) + void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num) + void OPENSSL_clear_free(void *str, size_t num) + void OPENSSL_cleanse(void *ptr, size_t len); + + unsigned char *OPENSSL_hexstr2buf(const char *str, long *len); + char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len); + int OPENSSL_hexchar2int(unsigned char c); + + void *CRYPTO_malloc(size_t num, const char *file, int line) + void *CRYPTO_zalloc(size_t num, const char *file, int line) + void *CRYPTO_realloc(void *p, size_t num, const char *file, int line) + void CRYPTO_free(void *str, const char *, int) + char *CRYPTO_strdup(const char *p, const char *file, int line) + char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line) + void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, const char *file, int line) + void CRYPTO_clear_free(void *str, size_t num, const char *, int) + + void CRYPTO_get_mem_functions( + void *(**m)(size_t, const char *, int), + void *(**r)(void *, size_t, const char *, int), + void (**f)(void *, const char *, int)) + int CRYPTO_set_mem_functions( + void *(*m)(size_t, const char *, int), + void *(*r)(void *, size_t, const char *, int), + void (*f)(void *, const char *, int)) + + int CRYPTO_set_mem_debug(int onoff) + + int CRYPTO_mem_ctrl(int mode); + + int OPENSSL_mem_debug_push(const char *info) + int OPENSSL_mem_debug_pop(void); + + int CRYPTO_mem_debug_push(const char *info, const char *file, int line); + int CRYPTO_mem_debug_pop(void); + + void CRYPTO_mem_leaks(BIO *b); + void CRYPTO_mem_leaks_fp(FILE *fp); + +=head1 DESCRIPTION + +OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are +generally macro's that add the standard C B<__FILE__> and B<__LINE__> +parameters and call a lower-level B<CRYPTO_xxx> API. +Some functions do not add those parameters, but exist for consistency. + +OPENSSL_malloc_init() sets the lower-level memory allocation functions +to their default implementation. +It is generally not necessary to call this, except perhaps in certain +shared-library situations. + +OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the +C malloc(), realloc(), and free() functions. +OPENSSL_zalloc() calls memset() to zero the memory before returning. + +OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used +when the buffer at B<addr> holds sensitive information. +The old buffer is filled with zero's by calling OPENSSL_cleanse() +before ultimately calling OPENSSL_free(). + +OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's. +Use OPENSSL_cleanse() with care if the memory is a mapping of a file. +If the storage controller uses write compression, then its possible +that sensitive tail bytes will survive zeroization because the block of +zeros will be compressed. If the storage controller uses wear leveling, +then the old sensitive data will not be overwritten; rather, a block of +0's will be written at a new physical location. + +OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the +equivalent C functions, except that memory is allocated by calling the +OPENSSL_malloc() and should be released by calling OPENSSL_free(). + +OPENSSL_strlcpy(), +OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C +library functions and are provided for portability. + +OPENSSL_hexstr2buf() parses B<str> as a hex string and returns a +pointer to the parsed value. The memory is allocated by calling +OPENSSL_malloc() and should be released by calling OPENSSL_free(). +If B<len> is not NULL, it is filled in with the output length. +Colons between two-character hex "bytes" are ignored. +An odd number of hex digits is an error. + +OPENSSL_buf2hexstr() takes the specified buffer and length, and returns +a hex string for value, or NULL on error. +B<Buffer> cannot be NULL; if B<len> is 0 an empty string is returned. + +OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent, +or returns -1 on error. + +If no allocations have been done, it is possible to "swap out" the default +implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free() +and replace them with alternate versions (hooks). +CRYPTO_get_mem_functions() function fills in the given arguments with the +function pointers for the current implementations. +With CRYPTO_set_mem_functions(), you can specify a different set of functions. +If any of B<m>, B<r>, or B<f> are NULL, then the function is not changed. + +The default implementation can include some debugging capability (if enabled +at build-time). +This adds some overhead by keeping a list of all memory allocations, and +removes items from the list when they are free'd. +This is most useful for identifying memory leaks. +CRYPTO_set_mem_debug() turns this tracking on and off. In order to have +any effect, is must be called before any of the allocation functions +(e.g., CRYPTO_malloc()) are called, and is therefore normally one of the +first lines of main() in an application. + +CRYPTO_mem_ctrl() provides fine-grained control of memory leak tracking. +To enable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of +the B<CRYPTO_MEM_CHECK_ON>. +To disable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of +the B<CRYPTO_MEM_CHECK_OFF>. + +While checking memory, it can be useful to store additional context +about what is being done. +For example, identifying the field names when parsing a complicated +data structure. +OPENSSL_mem_debug_push() (which calls CRYPTO_mem_debug_push()) +attachs an identifying string to the allocation stack. +This must be a global or other static string; it is not copied. +OPENSSL_mem_debug_pop() removes identifying state from the stack. + +At the end of the program, calling CRYPTO_mem_leaks() or +CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it +to the specified BIO B<b> or FILE B<fp>. These functions return 1 if +there are no leaks, 0 if there are leaks and -1 if an error occurred. + +=head1 RETURN VALUES + +OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free() +CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions() +return no value. + +CRYPTO_mem_leaks() and CRYPTO_mem_leaks_fp() return 1 if there +are no leaks, 0 if there are leaks and -1 if an error occurred. + +OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(), +OPENSSL_clear_realloc(), +CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(), +CRYPTO_clear_realloc(), +OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(), +OPENSSL_strdup(), and OPENSSL_strndup() +return a pointer to allocated memory or NULL on error. + +CRYPTO_set_mem_functions() and CRYPTO_set_mem_debug() +return 1 on success or 0 on failure (almost +always because allocations have already happened). + +CRYPTO_mem_ctrl() returns -1 if an error occurred, otherwise the +previous value of the mode. + +OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop() +return 1 on success or 0 on failure. + +=head1 NOTES + +While it's permitted to swap out only a few and not all the functions +with CRYPTO_set_mem_functions(), it's recommended to swap them all out +at once. I<This applies specially if OpenSSL was built with the +configuration option> C<crypto-mdebug> I<enabled. In case, swapping out +only, say, the malloc() implementation is outright dangerous.> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OPENSSL_secure_malloc.pod b/openssl-1.1.0h/doc/crypto/OPENSSL_secure_malloc.pod new file mode 100644 index 0000000..3f27d76 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OPENSSL_secure_malloc.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_initialized, +CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc, +OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free, +OPENSSL_secure_clear_free, CRYPTO_secure_free, CRYPTO_secure_clear_free, +OPENSSL_secure_actual_size, OPENSSL_secure_allocated, CRYPTO_secure_used +- secure heap storage + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + int CRYPTO_secure_malloc_init(size_t size, int minsize); + + int CRYPTO_secure_malloc_initialized(); + + int CRYPTO_secure_malloc_done(); + + void *OPENSSL_secure_malloc(size_t num); + void *CRYPTO_secure_malloc(size_t num, const char *file, int line); + + void *OPENSSL_secure_zalloc(size_t num); + void *CRYPTO_secure_zalloc(size_t num, const char *file, int line); + + void OPENSSL_secure_free(void* ptr); + void CRYPTO_secure_free(void *ptr, const char *, int); + + void OPENSSL_secure_clear_free(void* ptr, size_t num); + void CRYPTO_secure_clear_free(void *ptr, size_t num, const char *, int); + + size_t OPENSSL_secure_actual_size(const void *ptr); + int OPENSSL_secure_allocated(const void *ptr); + + size_t CRYPTO_secure_used(); + +=head1 DESCRIPTION + +In order to help protect applications (particularly long-running servers) +from pointer overruns or underruns that could return arbitrary data from +the program's dynamic memory area, where keys and other sensitive +information might be stored, OpenSSL supports the concept of a "secure heap." +The level and type of security guarantees depend on the operating system. +It is a good idea to review the code and see if it addresses your +threat model and concerns. + +If a secure heap is used, then private key B<BIGNUM> values are stored there. +This protects long-term storage of private keys, but will not necessarily +put all intermediate values and computations there. + +CRYPTO_secure_malloc_init() creates the secure heap, with the specified +C<size> in bytes. The C<minsize> parameter is the minimum size to +allocate from the heap. Both C<size> and C<minsize> must be a power +of two. + +CRYPTO_secure_malloc_initialized() indicates whether or not the secure +heap as been initialized and is available. + +CRYPTO_secure_malloc_done() releases the heap and makes the memory unavailable +to the process if all secure memory has been freed. +It can take noticeably long to complete. + +OPENSSL_secure_malloc() allocates C<num> bytes from the heap. +If CRYPTO_secure_malloc_init() is not called, this is equivalent to +calling OPENSSL_malloc(). +It is a macro that expands to +CRYPTO_secure_malloc() and adds the C<__FILE__> and C<__LINE__> parameters. + +OPENSSL_secure_zalloc() and CRYPTO_secure_zalloc() are like +OPENSSL_secure_malloc() and CRYPTO_secure_malloc(), respectively, +except that they call memset() to zero the memory before returning. + +OPENSSL_secure_free() releases the memory at C<ptr> back to the heap. +It must be called with a value previously obtained from +OPENSSL_secure_malloc(). +If CRYPTO_secure_malloc_init() is not called, this is equivalent to +calling OPENSSL_free(). +It exists for consistency with OPENSSL_secure_malloc() , and +is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__> +and C<__LINE__> parameters.. + +OPENSSL_secure_allocated() tells whether or not a pointer is within +the secure heap. +OPENSSL_secure_actual_size() tells the actual size allocated to the +pointer; implementations may allocate more space than initially +requested, in order to "round up" and reduce secure heap fragmentation. + +CRYPTO_secure_used() returns the number of bytes allocated in the +secure heap. + +=head1 RETURN VALUES + +CRYPTO_secure_malloc_init() returns 0 on failure, 1 if successful, +and 2 if successful but the heap could not be protected by memory +mapping. + +CRYPTO_secure_malloc_initialized() returns 1 if the secure heap is +available (that is, if CRYPTO_secure_malloc_init() has been called, +but CRYPTO_secure_malloc_done() has not been called or failed) or 0 if not. + +OPENSSL_secure_malloc() and OPENSSL_secure_zalloc() return a pointer into +the secure heap of the requested size, or C<NULL> if memory could not be +allocated. + +CRYPTO_secure_allocated() returns 1 if the pointer is in the secure heap, or 0 if not. + +CRYPTO_secure_malloc_done() returns 1 if the secure memory area is released, or 0 if not. + +OPENSSL_secure_free() and OPENSSL_secure_clear_free() return no values. + +=head1 SEE ALSO + +L<OPENSSL_malloc(3)>, +L<BN_new(3)> + +=head1 HISTORY + +OPENSSL_secure_clear_free() was added in OpenSSL 1.1.0g. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/OpenSSL_add_all_algorithms.pod b/openssl-1.1.0h/doc/crypto/OpenSSL_add_all_algorithms.pod new file mode 100644 index 0000000..aaa28dd --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/OpenSSL_add_all_algorithms.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests, EVP_cleanup - +add algorithms to internal table + +=head1 SYNOPSIS + + #include <openssl/evp.h> + +Deprecated: + + # if OPENSSL_API_COMPAT < 0x10100000L + void OpenSSL_add_all_algorithms(void); + void OpenSSL_add_all_ciphers(void); + void OpenSSL_add_all_digests(void); + + void EVP_cleanup(void) +# endif + +=head1 DESCRIPTION + +OpenSSL keeps an internal table of digest algorithms and ciphers. It uses +this table to lookup ciphers via functions such as EVP_get_cipher_byname(). In +OpenSSL versions prior to 1.1.0 these functions initialised and de-initialised +this table. From OpenSSL 1.1.0 they are deprecated. No explicit initialisation +or de-initialisation is required. See L<OPENSSL_init_crypto(3)> for further +information. + +OpenSSL_add_all_digests() adds all digest algorithms to the table. + +OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and +ciphers). + +OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including +password based encryption algorithms. + +In versions prior to 1.1.0 EVP_cleanup() removed all ciphers and digests from +the table. It no longer has any effect in OpenSSL 1.1.0. + +=head1 RETURN VALUES + +None of the functions return a value. + +=head1 NOTES + +A typical application will call OpenSSL_add_all_algorithms() initially and +EVP_cleanup() before exiting. + +An application does not need to add algorithms to use them explicitly, for example +by EVP_sha1(). It just needs to add them if it (or any of the functions it calls) +needs to lookup algorithms. + +The cipher and digest lookup functions are used in many parts of the library. If +the table is not initialized several functions will misbehave and complain they +cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME libraries. +This is a common query in the OpenSSL mailing lists. + +Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a +statically linked executable can be quite large. If this is important it is possible +to just add the required ciphers and digests. + +=head1 BUGS + +Although the functions do not return error codes it is possible for them to fail. +This will only happen as a result of a memory allocation failure so this is not +too much of a problem in practice. + +=head1 SEE ALSO + +L<evp(3)>, L<EVP_DigestInit(3)>, +L<EVP_EncryptInit(3)> + +=head1 HISTORY + +The OpenSSL_add_all_algorithms(), OpenSSL_add_all_ciphers(), +OpenSSL_add_all_digests(), and EVP_cleanup(), functions +were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto(). + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PEM_read.pod b/openssl-1.1.0h/doc/crypto/PEM_read.pod new file mode 100644 index 0000000..66cbc7d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PEM_read.pod @@ -0,0 +1,127 @@ +=pod + +=head1 NAME + +PEM_write, PEM_write_bio, +PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO +- PEM encoding routines + +=head1 SYNOPSIS + + #include <openssl/pem.h> + + int PEM_write(FILE *fp, const char *name, const char *header, + const unsigned char *data, long len) + int PEM_write_bio(BIO *bp, const char *name, const char *header, + const unsigned char *data, long len) + + int PEM_read(FILE *fp, char **name, char **header, + unsigned char **data, long *len); + int PEM_read_bio(BIO *bp, char **name, char **header, + unsigned char **data, long *len); + + int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo); + int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len, + pem_password_cb *cb, void *u); + +=head1 DESCRIPTION + +These functions read and write PEM-encoded objects, using the PEM +type B<name>, any additional B<header> information, and the raw +B<data> of length B<len>. + +PEM is the term used for binary content encoding first defined in IETF +RFC 1421. The content is a series of base64-encoded lines, surrounded +by begin/end markers each on their own line. For example: + + -----BEGIN PRIVATE KEY----- + MIICdg.... + ... bhTQ== + -----END PRIVATE KEY----- + +Optional header line(s) may appear after the begin line, and their +existence depends on the type of object being written or read. + +PEM_write() writes to the file B<fp>, while PEM_write_bio() writes to +the BIO B<bp>. The B<name> is the name to use in the marker, the +B<header> is the header value or NULL, and B<data> and B<len> specify +the data and its length. + +The final B<data> buffer is typically an ASN.1 object which can be decoded with +the B<d2i> function appropriate to the type B<name>; see L<d2i_X509(3)> +for examples. + +PEM_read() reads from the file B<fp>, while PEM_read_bio() reads +from the BIO B<bp>. +Both skip any non-PEM data that precedes the start of the next PEM object. +When an object is successfully retrieved, the type name from the "----BEGIN +<type>-----" is returned via the B<name> argument, any encapsulation headers +are returned in B<header> and the base64-decoded content and its length are +returned via B<data> and B<len> respectively. +The B<name>, B<header> and B<data> pointers are allocated via OPENSSL_malloc() +and should be freed by the caller via OPENSSL_free() when no longer needed. + +PEM_get_EVP_CIPHER_INFO() can be used to determine the B<data> returned by +PEM_read() or PEM_read_bio() is encrypted and to retrieve the associated cipher +and IV. +The caller passes a pointer to structure of type B<EVP_CIPHER_INFO> via the +B<cinfo> argument and the B<header> returned via PEM_read() or PEM_read_bio(). +If the call is successful 1 is returned and the cipher and IV are stored at the +address pointed to by B<cinfo>. +When the header is malformed, or not supported or when the cipher is unknown +or some internal error happens 0 is returned. +This function is deprecated, see B<NOTES> below. + +PEM_do_header() can then be used to decrypt the data if the header +indicates encryption. +The B<cinfo> argument is a pointer to the structure initialized by the previous +call to PEM_get_EVP_CIPHER_INFO(). +The B<data> and B<len> arguments are those returned by the previous call to +PEM_read() or PEM_read_bio(). +The B<cb> and B<u> arguments make it possible to override the default password +prompt function as described in L<PEM_read_PrivateKey(3)>. +On successful completion the B<data> is decrypted in place, and B<len> is +updated to indicate the plaintext length. +This function is deprecated, see B<NOTES> below. + +If the data is a priori known to not be encrypted, then neither PEM_do_header() +nor PEM_get_EVP_CIPHER_INFO() need be called. + +=head1 RETURN VALUES + +PEM_read() and PEM_read_bio() return 1 on success and 0 on failure, the latter +includes the case when no more PEM objects remain in the input file. +To distinguish end of file from more serious errors the caller must peek at the +error stack and check for B<PEM_R_NO_START_LINE>, which indicates that no more +PEM objects were found. See L<ERR_peek_last_error(3)>, L<ERR_GET_REASON(3)>. + +PEM_get_EVP_CIPHER_INFO() and PEM_do_header() return 1 on success, and 0 on +failure. +The B<data> is likely meaningless if these functions fail. + +=head1 NOTES + +The PEM_get_EVP_CIPHER_INFO() and PEM_do_header() functions are deprecated. +This is because the underlying PEM encryption format is obsolete, and should +be avoided. +It uses an encryption format with an OpenSSL-specific key-derivation function, +which employs MD5 with an iteration count of 1! +Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5 +v2.0 PBE. +See L<PEM_write_PrivateKey(3)> and L<d2i_PKCS8PrivateKey_bio(3)>. + +=head1 SEE ALSO + +L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>, +L<d2i_PKCS8PrivateKey_bio(3)>. + +=head1 COPYRIGHT + +Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PEM_read_CMS.pod b/openssl-1.1.0h/doc/crypto/PEM_read_CMS.pod new file mode 100644 index 0000000..649c808 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PEM_read_CMS.pod @@ -0,0 +1,97 @@ +=pod + +=head1 NAME + +DECLARE_PEM_rw, +PEM_read_CMS, +PEM_read_bio_CMS, +PEM_write_CMS, +PEM_write_bio_CMS, +PEM_write_DHxparams, +PEM_write_bio_DHxparams, +PEM_read_ECPKParameters, +PEM_read_bio_ECPKParameters, +PEM_write_ECPKParameters, +PEM_write_bio_ECPKParameters, +PEM_read_ECPrivateKey, +PEM_write_ECPrivateKey, +PEM_write_bio_ECPrivateKey, +PEM_read_EC_PUBKEY, +PEM_read_bio_EC_PUBKEY, +PEM_write_EC_PUBKEY, +PEM_write_bio_EC_PUBKEY, +PEM_read_NETSCAPE_CERT_SEQUENCE, +PEM_read_bio_NETSCAPE_CERT_SEQUENCE, +PEM_write_NETSCAPE_CERT_SEQUENCE, +PEM_write_bio_NETSCAPE_CERT_SEQUENCE, +PEM_read_PKCS8, +PEM_read_bio_PKCS8, +PEM_write_PKCS8, +PEM_write_bio_PKCS8, +PEM_write_PKCS8_PRIV_KEY_INFO, +PEM_read_bio_PKCS8_PRIV_KEY_INFO, +PEM_read_PKCS8_PRIV_KEY_INFO, +PEM_write_bio_PKCS8_PRIV_KEY_INFO, +PEM_read_SSL_SESSION, +PEM_read_bio_SSL_SESSION, +PEM_write_SSL_SESSION, +PEM_write_bio_SSL_SESSION +- PEM object encoding routines + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/pem.h> + + DECLARE_PEM_rw(name, TYPE) + + TYPE *PEM_read_TYPE(FILE *fp, TYPE **a, pem_password_cb *cb, void *u); + TYPE *PEM_read_bio_TYPE(BIO *bp, TYPE **a, pem_password_cb *cb, void *u); + int PEM_write_TYPE(FILE *fp, const TYPE *a); + int PEM_write_bio_TYPE(BIO *bp, const TYPE *a); + +=head1 DESCRIPTION + +In the description below, I<TYPE> is used +as a placeholder for any of the OpenSSL datatypes, such as I<X509>. +The macro B<DECLARE_PEM_rw> expands to the set of declarations shown in +the next four lines of the synopsis. + +These routines convert between local instances of ASN1 datatypes and +the PEM encoding. For more information on the templates, see +L<ASN1_ITEM(3)>. For more information on the lower-level routines used +by the functions here, see L<PEM_read(3)>. + +PEM_read_TYPE() reads a PEM-encoded object of I<TYPE> from the file B<fp> +and returns it. The B<cb> and B<u> parameters are as described in +L<pem_password_cb(3)>. + +PEM_read_bio_TYPE() is similar to PEM_read_TYPE() but reads from the BIO B<bp>. + +PEM_write_TYPE() writes the PEM encoding of the object B<a> to the file B<fp>. + +PEM_write_bio_TYPE() similarly writes to the BIO B<bp>. + +=head1 RETURN VALUES + +PEM_read_TYPE() and PEM_read_bio_TYPE() return a pointer to an allocated +object, which should be released by calling TYPE_free(), or NULL on error. + +PEM_write_TYPE() and PEM_write_bio_TYPE() return the number of bytes written +or zero on error. + +=head1 SEE ALSO + +L<PEM_read(3)> + +=head1 COPYRIGHT + +Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PEM_read_bio_PrivateKey.pod b/openssl-1.1.0h/doc/crypto/PEM_read_bio_PrivateKey.pod new file mode 100644 index 0000000..6b3006e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PEM_read_bio_PrivateKey.pod @@ -0,0 +1,481 @@ +=pod + +=head1 NAME + +pem_password_cb, +PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, +PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey, +PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, +PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, +PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, +PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, +PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, +PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, +PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, +PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, +PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, +PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, +PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, +PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, +PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, +PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, +PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, +PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, +PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, +PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, +PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, +PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines + +=head1 SYNOPSIS + + #include <openssl/pem.h> + + typedef int pem_password_cb(char *buf, int size, int rwflag, void *u); + + EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x, + const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, + char *kstr, int klen, + pem_password_cb *cb, void *u); + int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, + char *kstr, int klen, + pem_password_cb *cb, void *u); + int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, + char *kstr, int klen, + pem_password_cb *cb, void *u); + int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); + int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); + + RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); + int PEM_write_RSAPublicKey(FILE *fp, RSA *x); + + RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); + int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); + + DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, + pem_password_cb *cb, void *u); + DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, + pem_password_cb *cb, void *u); + DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); + int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); + + DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); + DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); + int PEM_write_bio_DSAparams(BIO *bp, DSA *x); + int PEM_write_DSAparams(FILE *fp, DSA *x); + + DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); + DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); + int PEM_write_bio_DHparams(BIO *bp, DH *x); + int PEM_write_DHparams(FILE *fp, DH *x); + + X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); + X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); + int PEM_write_bio_X509(BIO *bp, X509 *x); + int PEM_write_X509(FILE *fp, X509 *x); + + X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); + X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); + int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); + int PEM_write_X509_AUX(FILE *fp, X509 *x); + + X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, + pem_password_cb *cb, void *u); + X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); + int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); + int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); + int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); + + X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, + pem_password_cb *cb, void *u); + X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); + int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); + + PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); + PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); + int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); + int PEM_write_PKCS7(FILE *fp, PKCS7 *x); + +=head1 DESCRIPTION + +The PEM functions read or write structures in PEM format. In +this sense PEM format is simply base64 encoded data surrounded +by header lines. + +For more details about the meaning of arguments see the +B<PEM FUNCTION ARGUMENTS> section. + +Each operation has four functions associated with it. For +clarity the term "B<foobar> functions" will be used to collectively +refer to the PEM_read_bio_foobar(), PEM_read_foobar(), +PEM_write_bio_foobar() and PEM_write_foobar() functions. + +The B<PrivateKey> functions read or write a private key in PEM format using an +EVP_PKEY structure. The write routines use PKCS#8 private key format and are +equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently +handle traditional and PKCS#8 format encrypted and unencrypted keys. + +PEM_write_bio_PrivateKey_traditional() writes out a private key in legacy +"traditional" format. + +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 algorithm to use: unlike some 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. + +PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() +also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however +it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm +to use is specified in the B<nid> parameter and should be the NID of the +corresponding OBJECT IDENTIFIER (see NOTES section). + +The B<PUBKEY> functions process a public key using an EVP_PKEY +structure. The public key is encoded as a SubjectPublicKeyInfo +structure. + +The B<RSAPrivateKey> functions process an RSA private key using an +RSA structure. The write routines uses traditional format. The read +routines handles the same formats as the B<PrivateKey> +functions but an error occurs if the private key is not RSA. + +The B<RSAPublicKey> functions process an RSA public key using an +RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey +structure. + +The B<RSA_PUBKEY> functions also process an RSA public key using +an RSA structure. However the public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not RSA. + +The B<DSAPrivateKey> functions process a DSA private key using a +DSA structure. The write routines uses traditional format. The read +routines handles the same formats as the B<PrivateKey> +functions but an error occurs if the private key is not DSA. + +The B<DSA_PUBKEY> functions process a DSA public key using +a DSA structure. The public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not DSA. + +The B<DSAparams> functions process DSA parameters using a DSA +structure. The parameters are encoded using a Dss-Parms structure +as defined in RFC2459. + +The B<DHparams> functions process DH parameters using a DH +structure. The parameters are encoded using a PKCS#3 DHparameter +structure. + +The B<X509> functions process an X509 certificate using an X509 +structure. They will also process a trusted X509 certificate but +any trust settings are discarded. + +The B<X509_AUX> functions process a trusted X509 certificate using +an X509 structure. + +The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10 +certificate request using an X509_REQ structure. The B<X509_REQ> +write functions use B<CERTIFICATE REQUEST> in the header whereas +the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST> +(as required by some CAs). The B<X509_REQ> read functions will +handle either form so there are no B<X509_REQ_NEW> read functions. + +The B<X509_CRL> functions process an X509 CRL using an X509_CRL +structure. + +The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7 +structure. + +=head1 PEM FUNCTION ARGUMENTS + +The PEM functions have many common arguments. + +The B<bp> BIO parameter (if present) specifies the BIO to read from +or write to. + +The B<fp> FILE parameter (if present) specifies the FILE pointer to +read from or write to. + +The PEM read functions all take an argument B<TYPE **x> and return +a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function +uses. If B<x> is NULL then the parameter is ignored. If B<x> is not +NULL but B<*x> is NULL then the structure returned will be written +to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made +to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections). +Irrespective of the value of B<x> a pointer to the structure is always +returned (or NULL if an error occurred). + +The PEM functions which write private keys take an B<enc> parameter +which specifies the encryption algorithm to use, encryption is done +at the PEM level. If this parameter is set to NULL then the private +key is written in unencrypted form. + +The B<cb> argument is the callback to use when querying for the pass +phrase used for encrypted PEM structures (normally only private keys). + +For the PEM write routines if the B<kstr> parameter is not NULL then +B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is +ignored. + +If the B<cb> parameters is set to NULL and the B<u> parameter is not +NULL then the B<u> parameter is interpreted as a null terminated string +to use as the passphrase. If both B<cb> and B<u> are NULL then the +default callback routine is used which will typically prompt for the +passphrase on the current terminal with echoing turned off. + +The default passphrase callback is sometimes inappropriate (for example +in a GUI application) so an alternative can be supplied. The callback +routine has the following form: + + int cb(char *buf, int size, int rwflag, void *u); + +B<buf> is the buffer to write the passphrase to. B<size> is the maximum +length of the passphrase (i.e. the size of buf). B<rwflag> is a flag +which is set to 0 when reading and 1 when writing. A typical routine +will ask the user to verify the passphrase (for example by prompting +for it twice) if B<rwflag> is 1. The B<u> parameter has the same +value as the B<u> parameter passed to the PEM routine. It allows +arbitrary data to be passed to the callback by the application +(for example a window handle in a GUI application). The callback +B<must> return the number of characters in the passphrase or 0 if +an error occurred. + +=head1 EXAMPLES + +Although the PEM routines take several arguments in almost all applications +most of them are set to 0 or NULL. + +Read a certificate in PEM format from a BIO: + + X509 *x; + x = PEM_read_bio_X509(bp, NULL, 0, NULL); + if (x == NULL) { + /* Error */ + } + +Alternative method: + + X509 *x = NULL; + if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { + /* Error */ + } + +Write a certificate to a BIO: + + if (!PEM_write_bio_X509(bp, x)) { + /* Error */ + } + +Write a private key (using traditional format) to a BIO using +triple DES encryption, the pass phrase is prompted for: + + if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) { + /* Error */ + } + +Write a private key (using PKCS#8 format) to a BIO using triple +DES encryption, using the pass phrase "hello": + + if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) { + /* Error */ + } + +Read a private key from a BIO using a pass phrase callback: + + key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); + if (key == NULL) { + /* Error */ + } + +Skeleton pass phrase callback: + + int pass_cb(char *buf, int size, int rwflag, void *u) + { + int len; + char *tmp; + + /* We'd probably do something else if 'rwflag' is 1 */ + printf("Enter pass phrase for \"%s\"\n", (char *)u); + + /* get pass phrase, length 'len' into 'tmp' */ + tmp = "hello"; + len = strlen(tmp); + if (len <= 0) + return 0; + + if (len > size) + len = size; + memcpy(buf, tmp, len); + return len; + } + +=head1 NOTES + +The old B<PrivateKey> write routines are retained for compatibility. +New applications should write private keys using the +PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines +because they are more secure (they use an iteration count of 2048 whereas +the traditional routines use a count of 1) unless compatibility with older +versions of OpenSSL is important. + +The B<PrivateKey> read routines can be used in all applications because +they handle all formats transparently. + +A frequent cause of problems is attempting to use the PEM routines like +this: + + X509 *x; + PEM_read_bio_X509(bp, &x, 0, NULL); + +this is a bug because an attempt will be made to reuse the data at B<x> +which is an uninitialised pointer. + +=head1 PEM ENCRYPTION FORMAT + +These old B<PrivateKey> routines use a non standard technique for encryption. + +The private key (or other data) takes the following form: + + -----BEGIN RSA PRIVATE KEY----- + Proc-Type: 4,ENCRYPTED + DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 + + ...base64 encoded data... + -----END RSA PRIVATE KEY----- + +The line beginning with I<Proc-Type> contains the version and the +protection on the encapsulated data. The line beginning I<DEK-Info> +contains two comma separated values: the encryption algorithm name as +used by EVP_get_cipherbyname() and an initialization vector used by the +cipher encoded as a set of hexadecimal digits. After those two lines is +the base64-encoded encrypted data. + +The encryption key is derived using EVP_BytesToKey(). The cipher's +initialization vector is passed to EVP_BytesToKey() as the B<salt> +parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used +(regardless of the size of the initialization vector). The user's +password is passed to EVP_BytesToKey() using the B<data> and B<datal> +parameters. Finally, the library uses an iteration count of 1 for +EVP_BytesToKey(). + +The B<key> derived by EVP_BytesToKey() along with the original initialization +vector is then used to decrypt the encrypted data. The B<iv> produced by +EVP_BytesToKey() is not utilized or needed, and NULL should be passed to +the function. + +The pseudo code to derive the key would look similar to: + + EVP_CIPHER* cipher = EVP_des_ede3_cbc(); + EVP_MD* md = EVP_md5(); + + unsigned int nkey = EVP_CIPHER_key_length(cipher); + unsigned int niv = EVP_CIPHER_iv_length(cipher); + unsigned char key[nkey]; + unsigned char iv[niv]; + + memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv); + rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/); + if (rc != nkey) { + /* Error */ + } + + /* On success, use key and iv to initialize the cipher */ + +=head1 BUGS + +The PEM read routines in some versions of OpenSSL will not correctly reuse +an existing structure. Therefore the following: + + PEM_read_bio_X509(bp, &x, 0, NULL); + +where B<x> already contains a valid certificate, may not work, whereas: + + X509_free(x); + x = PEM_read_bio_X509(bp, NULL, 0, NULL); + +is guaranteed to work. + +=head1 RETURN CODES + +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 HISTORY + +The old Netscape certificate sequences were no longer documented +in OpenSSL 1.1; applications should use the PKCS7 standard instead +as they will be formally deprecated in a future releases. + +=head1 SEE ALSO + +L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PEM_write_bio_CMS_stream.pod b/openssl-1.1.0h/doc/crypto/PEM_write_bio_CMS_stream.pod new file mode 100644 index 0000000..c73fafd --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PEM_write_bio_CMS_stream.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); + +=head1 DESCRIPTION + +PEM_write_bio_CMS_stream() outputs a CMS_ContentInfo structure in PEM format. + +It is otherwise identical to the function SMIME_write_CMS(). + +=head1 NOTES + +This function is effectively a version of the PEM_write_bio_CMS() supporting +streaming. + +=head1 RETURN VALUES + +PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_verify(3)>, L<CMS_encrypt(3)> +L<CMS_decrypt(3)>, +L<PEM_write(3)>, +L<SMIME_write_CMS(3)>, +L<i2d_CMS_bio_stream(3)> + +=head1 HISTORY + +PEM_write_bio_CMS_stream() was added to OpenSSL 1.0.0 + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PEM_write_bio_PKCS7_stream.pod b/openssl-1.1.0h/doc/crypto/PEM_write_bio_PKCS7_stream.pod new file mode 100644 index 0000000..77f97aa --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PEM_write_bio_PKCS7_stream.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); + +=head1 DESCRIPTION + +PEM_write_bio_PKCS7_stream() outputs a PKCS7 structure in PEM format. + +It is otherwise identical to the function SMIME_write_PKCS7(). + +=head1 NOTES + +This function is effectively a version of the PEM_write_bio_PKCS7() supporting +streaming. + +=head1 RETURN VALUES + +PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<PKCS7_sign(3)>, +L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)>, +L<SMIME_write_PKCS7(3)>, +L<i2d_PKCS7_bio_stream(3)> + +=head1 HISTORY + +PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0 + +=head1 COPYRIGHT + +Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS12_create.pod b/openssl-1.1.0h/doc/crypto/PKCS12_create.pod new file mode 100644 index 0000000..0a43b96 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS12_create.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +PKCS12_create - create a PKCS#12 structure + +=head1 SYNOPSIS + + #include <openssl/pkcs12.h> + + PKCS12 *PKCS12_create(const char *pass, const char *name, EVP_PKEY *pkey, + X509 *cert, STACK_OF(X509) *ca, + int nid_key, int nid_cert, int iter, int mac_iter, int keytype); + +=head1 DESCRIPTION + +PKCS12_create() creates a PKCS#12 structure. + +B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for +the supplied certificate and key. B<pkey> is the private key to include in +the structure and B<cert> its corresponding certificates. B<ca>, if not B<NULL> +is an optional set of certificates to also include in the structure. + +B<nid_key> and B<nid_cert> are the encryption algorithms that should be used +for the key and certificate respectively. B<iter> is the encryption algorithm +iteration count to use and B<mac_iter> is the MAC iteration count to use. +B<keytype> is the type of key. + +=head1 NOTES + +The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype> +can all be set to zero and sensible defaults will be used. + +These defaults are: 40 bit RC2 encryption for certificates, triple DES +encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER +(currently 2048) and a MAC iteration count of 1. + +The default MAC iteration count is 1 in order to retain compatibility with +old software which did not interpret MAC iteration counts. If such compatibility +is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER. + +B<keytype> adds a flag to the store private key. This is a non standard extension +that is only currently interpreted by MSIE. If set to zero the flag is omitted, +if set to B<KEY_SIG> the key can be used for signing only, if set to B<KEY_EX> +it can be used for signing and encryption. This option was useful for old +export grade software which could use signing only keys of arbitrary size but +had restrictions on the permissible sizes of keys which could be used for +encryption. + +If a certificate contains an B<alias> or B<keyid> then this will be +used for the corresponding B<friendlyName> or B<localKeyID> in the +PKCS12 structure. + +Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or +certificate is required. In previous versions both had to be present or +a fatal error is returned. + +B<nid_key> or B<nid_cert> can be set to -1 indicating that no encryption +should be used. + +B<mac_iter> can be set to -1 and the MAC will then be omitted entirely. + +=head1 SEE ALSO + +L<d2i_PKCS12(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS12_newpass.pod b/openssl-1.1.0h/doc/crypto/PKCS12_newpass.pod new file mode 100644 index 0000000..6b22fd7 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS12_newpass.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +PKCS12_newpass - change the password of a PKCS12 structure + +=head1 SYNOPSIS + + #include <openssl/pkcs12.h> + + int PKCS12_newpass(PKCS12 *p12, const char *oldpass, const char *newpass); + +=head1 DESCRIPTION + +PKCS12_newpass() changes the password of a PKCS12 structure. + +B<p12> is a pointer to a PKCS12 structure. B<oldpass> is the existing password +and B<newpass> is the new password. + +=head1 NOTES + +Each of B<oldpass> and B<newpass> is independently interpreted as a string in +the UTF-8 encoding. If it is not valid UTF-8, it is assumed to be ISO8859-1 +instead. + +In particular, this means that passwords in the locale character set +(or code page on Windows) must potentially be converted to UTF-8 before +use. This may include passwords from local text files, or input from +the terminal or command line. Refer to the documentation of +L<UI_OpenSSL(3)>, for example. + +=head1 RETURN VALUES + +PKCS12_newpass() returns 1 on success or 0 on failure. Applications can +retrieve the most recent error from PKCS12_newpass() with ERR_get_error(). + +=head1 EXAMPLE + +This example loads a PKCS#12 file, changes its password and writes out +the result to a new file. + + #include <stdio.h> + #include <stdlib.h> + #include <openssl/pem.h> + #include <openssl/err.h> + #include <openssl/pkcs12.h> + + int main(int argc, char **argv) + { + FILE *fp; + PKCS12 *p12; + if (argc != 5) { + fprintf(stderr, "Usage: pkread p12file password newpass opfile\n"); + return 1; + } + if ((fp = fopen(argv[1], "rb")) == NULL) { + fprintf(stderr, "Error opening file %s\n", argv[1]); + return 1; + } + p12 = d2i_PKCS12_fp(fp, NULL); + fclose(fp); + if (p12 == NULL) { + fprintf(stderr, "Error reading PKCS#12 file\n"); + ERR_print_errors_fp(stderr); + return 1; + } + if (PKCS12_newpass(p12, argv[2], argv[3]) == 0) { + fprintf(stderr, "Error changing password\n"); + ERR_print_errors_fp(stderr); + PKCS12_free(p12); + return 1; + } + if ((fp = fopen(argv[4], "wb")) == NULL) { + fprintf(stderr, "Error opening file %s\n", argv[4]); + PKCS12_free(p12); + return 1; + } + i2d_PKCS12_fp(fp, p12); + PKCS12_free(p12); + fclose(fp); + return 0; + } + + +=head1 NOTES + +If the PKCS#12 structure does not have a password, then you must use the empty +string "" for B<oldpass>. Using NULL for B<oldpass> will result in a +PKCS12_newpass() failure. + +If the wrong password is used for B<oldpass> then the function will fail, +with a MAC verification error. In rare cases the PKCS12 structure does not +contain a MAC: in this case it will usually fail with a decryption padding +error. + +=head1 BUGS + +The password format is a NULL terminated ASCII string which is converted to +Unicode form internally. As a result some passwords cannot be supplied to +this function. + +=head1 SEE ALSO + +L<PKCS12_create(3)>, L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS12_parse.pod b/openssl-1.1.0h/doc/crypto/PKCS12_parse.pod new file mode 100644 index 0000000..c03c371 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS12_parse.pod @@ -0,0 +1,71 @@ +=pod + +=head1 NAME + +PKCS12_parse - parse a PKCS#12 structure + +=head1 SYNOPSIS + + #include <openssl/pkcs12.h> + +int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca); + +=head1 DESCRIPTION + +PKCS12_parse() parses a PKCS12 structure. + +B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use. +If successful the private key will be written to B<*pkey>, the corresponding +certificate to B<*cert> and any additional certificates to B<*ca>. + +=head1 NOTES + +The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in +which case additional certificates will be discarded. B<*ca> can also be a +valid STACK in which case additional certificates are appended to B<*ca>. If +B<*ca> is B<NULL> a new STACK will be allocated. + +The B<friendlyName> and B<localKeyID> attributes (if present) on each +certificate will be stored in the B<alias> and B<keyid> attributes of the +B<X509> structure. + +The parameter B<pass> is interpreted as a string in the UTF-8 encoding. If it +is not valid UTF-8, then it is assumed to be ISO8859-1 instead. + +In particular, this means that passwords in the locale character set +(or code page on Windows) must potentially be converted to UTF-8 before +use. This may include passwords from local text files, or input from +the terminal or command line. Refer to the documentation of +L<UI_OpenSSL(3)>, for example. + +=head1 RETURN VALUES + +PKCS12_parse() returns 1 for success and zero if an error occurred. + +The error can be obtained from L<ERR_get_error(3)> + +=head1 BUGS + +Only a single private key and corresponding certificate is returned by this +function. More complex PKCS#12 files with multiple private keys will only +return the first match. + +Only B<friendlyName> and B<localKeyID> attributes are currently stored in +certificates. Other attributes are discarded. + +Attributes currently cannot be stored in the private key B<EVP_PKEY> structure. + +=head1 SEE ALSO + +L<d2i_PKCS12(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS5_PBKDF2_HMAC.pod b/openssl-1.1.0h/doc/crypto/PKCS5_PBKDF2_HMAC.pod new file mode 100644 index 0000000..5cc2caa --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS5_PBKDF2_HMAC.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +PKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 - password based derivation routines with salt and iteration count + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int PKCS5_PBKDF2_HMAC(const char *pass, int passlen, + const unsigned char *salt, int saltlen, int iter, + const EVP_MD *digest, + int keylen, unsigned char *out); + +int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen, + const unsigned char *salt, int saltlen, int iter, + int keylen, unsigned char *out); + +=head1 DESCRIPTION + +PKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count +as specified in RFC 2898. + +B<pass> is the password used in the derivation of length B<passlen>. B<pass> +is an optional parameter and can be NULL. If B<passlen> is -1, then the +function will calculate the length of B<pass> using strlen(). + +B<salt> is the salt used in the derivation of length B<saltlen>. If the +B<salt> is NULL, then B<saltlen> must be 0. The function will not +attempt to calculate the length of the B<salt> because it is not assumed to +be NULL terminated. + +B<iter> is the iteration count and its value should be greater than or +equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any +B<iter> less than 1 is treated as a single iteration. + +B<digest> is the message digest function used in the derivation. Values include +any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls +PKCS5_PBKDF2_HMAC() with EVP_sha1(). + +The derived key will be written to B<out>. The size of the B<out> buffer +is specified via B<keylen>. + +=head1 NOTES + +A typical application of this function is to derive keying material for an +encryption algorithm from a password in the B<pass>, a salt in B<salt>, +and an iteration count. + +Increasing the B<iter> parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. + +=head1 RETURN VALUES + +PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error. + +=head1 SEE ALSO + +L<evp(3)>, L<rand(3)>, +L<EVP_BytesToKey(3)> + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS7_decrypt.pod b/openssl-1.1.0h/doc/crypto/PKCS7_decrypt.pod new file mode 100644 index 0000000..4ed8aa7 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS7_decrypt.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags); + +=head1 DESCRIPTION + +PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData +structure. B<pkey> is the private key of the recipient, B<cert> is the +recipients certificate, B<data> is a BIO to write the content to and +B<flags> is an optional set of flags. + +=head1 NOTES + +Although the recipients certificate is not needed to decrypt the data it is needed +to locate the appropriate (of possible several) recipients in the PKCS#7 structure. + +The following flags can be passed in the B<flags> parameter. + +If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted +from the content. If the content is not of type B<text/plain> then an error is +returned. + +=head1 RETURN VALUES + +PKCS7_decrypt() returns either 1 for success or 0 for failure. +The error can be obtained from ERR_get_error(3) + +=head1 BUGS + +PKCS7_decrypt() must be passed the correct recipient key and certificate. It would +be better if it could look up the correct key and certificate from a database. + +The lack of single pass processing and need to hold all data in memory as +mentioned in PKCS7_sign() also applies to PKCS7_verify(). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<PKCS7_encrypt(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS7_encrypt.pod b/openssl-1.1.0h/doc/crypto/PKCS7_encrypt.pod new file mode 100644 index 0000000..4e1afc9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS7_encrypt.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +PKCS7_encrypt - create a PKCS#7 envelopedData structure + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags); + +=head1 DESCRIPTION + +PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs> +is a list of recipient certificates. B<in> is the content to be encrypted. +B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. + +=head1 NOTES + +Only RSA keys are supported in PKCS#7 and envelopedData so the recipient +certificates supplied to this function must all contain RSA public keys, though +they do not have to be signed using the RSA algorithm. + +EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use +because most clients will support it. + +Some old "export grade" clients may only support weak encryption using 40 or 64 +bit RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc() +respectively. + +The algorithm passed in the B<cipher> parameter must support ASN1 encoding of +its parameters. + +Many browsers implement a "sign and encrypt" option which is simply an S/MIME +envelopedData containing an S/MIME signed message. This can be readily produced +by storing the S/MIME signed message in a memory BIO and passing it to +PKCS7_encrypt(). + +The following flags can be passed in the B<flags> parameter. + +If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are +prepended to the data. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. If B<PKCS7_BINARY> is set then +B<PKCS7_TEXT> is ignored. + +If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output +suitable for streaming I/O: no data is read from the BIO B<in>. + +=head1 NOTES + +If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> +complete and outputting its contents via a function that does not +properly finalize the B<PKCS7> structure will give unpredictable +results. + +Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), +PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B<BIO> directly using +BIO_new_PKCS7(). + +=head1 RETURN VALUES + +PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred. +The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<PKCS7_decrypt(3)> + +=head1 HISTORY + +The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS7_sign.pod b/openssl-1.1.0h/doc/crypto/PKCS7_sign.pod new file mode 100644 index 0000000..f319f66 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS7_sign.pod @@ -0,0 +1,124 @@ +=pod + +=head1 NAME + +PKCS7_sign - create a PKCS#7 signedData structure + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); + +=head1 DESCRIPTION + +PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is +the certificate to sign with, B<pkey> is the corresponding private key. +B<certs> is an optional additional set of certificates to include in the PKCS#7 +structure (for example any intermediate CAs in the chain). + +The data to be signed is read from BIO B<data>. + +B<flags> is an optional set of flags. + +=head1 NOTES + +Any of the following flags (ored together) can be passed in the B<flags> +parameter. + +Many S/MIME clients expect the signed content to include valid MIME headers. If +the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended +to the data. + +If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the +PKCS7 structure, the signer's certificate must still be supplied in the +B<signcert> parameter though. This can reduce the size of the signature if the +signers certificate can be obtained by other means: for example a previously +signed message. + +The data being signed is included in the PKCS7 structure, unless +B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7 +detached signatures which are used in S/MIME plaintext signed messages for +example. + +Normally the supplied content is translated into MIME canonical format (as +required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation +occurs. This option should be used if the supplied data is in binary format +otherwise the translation will corrupt it. + +The signedData structure includes several PKCS#7 authenticatedAttributes +including the signing time, the PKCS#7 content type and the supported list of +ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no +authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just +the SMIMECapabilities are omitted. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of +these algorithms is disabled then it will not be included. + +If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is +just initialized ready to perform the signing operation. The signing is however +B<not> performed and the data to be signed is not read from the B<data> +parameter. Signing is deferred until after the data has been written. In this +way data can be signed in a single pass. + +If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to +which additional signers and capabilities can be added before finalization. + + +=head1 NOTES + +If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> +complete and outputting its contents via a function that does not properly +finalize the B<PKCS7> structure will give unpredictable results. + +Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), +PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization +can be performed by obtaining the streaming ASN1 B<BIO> directly using +BIO_new_PKCS7(). + +If a signer is specified it will use the default digest for the signing +algorithm. This is B<SHA1> for both RSA and DSA keys. + +The B<certs>, B<signcert> and B<pkey> parameters can all be +B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added +using the function PKCS7_sign_add_signer(). PKCS7_final() must also be +called to finalize the structure if streaming is not enabled. Alternative +signing digests can also be specified using this method. + +If B<signcert> and B<pkey> are NULL then a certificates only +PKCS#7 structure is output. + +In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must +B<NOT> be NULL. + +=head1 BUGS + +Some advanced attributes such as counter signatures are not supported. + +=head1 RETURN VALUES + +PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error +occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<PKCS7_verify(3)> + +=head1 HISTORY + +The B<PKCS7_PARTIAL> flag, and the ability for B<certs>, B<signcert>, +and B<pkey> parameters to be B<NULL> to be was added in OpenSSL 1.0.0 + +The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0 + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS7_sign_add_signer.pod b/openssl-1.1.0h/doc/crypto/PKCS7_sign_add_signer.pod new file mode 100644 index 0000000..88fef77 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS7_sign_add_signer.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +PKCS7_sign_add_signer - add a signer PKCS7 signed data structure + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags); + + +=head1 DESCRIPTION + +PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private +key B<pkey> using message digest B<md> to a PKCS7 signed data structure +B<p7>. + +The PKCS7 structure should be obtained from an initial call to PKCS7_sign() +with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7 +signed data structure. + +If the B<md> parameter is B<NULL> then the default digest for the public +key algorithm will be used. + +Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure +is not complete and must be finalized either by streaming (if applicable) or +a call to PKCS7_final(). + + +=head1 NOTES + +The main purpose of this function is to provide finer control over a PKCS#7 +signed data structure where the simpler PKCS7_sign() function defaults are +not appropriate. For example if multiple signers or non default digest +algorithms are needed. + +Any of the following flags (ored together) can be passed in the B<flags> +parameter. + +If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content +digest value from the PKCS7 structure: to add a signer to an existing structure. +An error occurs if a matching digest value cannot be found to copy. The +returned PKCS7 structure will be valid and finalized when this flag is set. + +If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the +B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes +can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is +needed to finalize it. + +If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the +PKCS7 structure, the signer's certificate must still be supplied in the +B<signcert> parameter though. This can reduce the size of the signature if the +signers certificate can be obtained by other means: for example a previously +signed message. + +The signedData structure includes several PKCS#7 authenticatedAttributes +including the signing time, the PKCS#7 content type and the supported list of +ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no +authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just +the SMIMECapabilities are omitted. + +If present the SMIMECapabilities attribute indicates support for the following +algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of +these algorithms is disabled then it will not be included. + + +PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO +structure just added, this can be used to set additional attributes +before it is finalized. + +=head1 RETURN VALUES + +PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO +structure just added or NULL if an error occurs. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<PKCS7_sign(3)>, +L<PKCS7_final(3)>, + +=head1 HISTORY + +PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0 + +=head1 COPYRIGHT + +Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/PKCS7_verify.pod b/openssl-1.1.0h/doc/crypto/PKCS7_verify.pod new file mode 100644 index 0000000..c34808e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/PKCS7_verify.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags); + + STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); + +=head1 DESCRIPTION + +PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7 +structure to verify. B<certs> is a set of certificates in which to search for +the signer's certificate. B<store> is a trusted certificate store (used for +chain verification). B<indata> is the signed data if the content is not +present in B<p7> (that is it is detached). The content is written to B<out> +if it is not NULL. + +B<flags> is an optional set of flags, which can be used to modify the verify +operation. + +PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does +B<not> check their validity or whether any signatures are valid. The B<certs> +and B<flags> parameters have the same meanings as in PKCS7_verify(). + +=head1 VERIFY PROCESS + +Normally the verify process proceeds as follows. + +Initially some sanity checks are performed on B<p7>. The type of B<p7> must +be signedData. There must be at least one signature on the data and if +the content is detached B<indata> cannot be B<NULL>. If the content is +not detached and B<indata> is not B<NULL>, then the structure has both +embedded and external content. To treat this as an error, use the flag +B<PKCS7_NO_DUAL_CONTENT>. +The default behavior allows this, for compatibility with older +versions of OpenSSL. + +An attempt is made to locate all the signer's certificates, first looking in +the B<certs> parameter (if it is not B<NULL>) and then looking in any certificates +contained in the B<p7> structure itself. If any signer's certificates cannot be +located the operation fails. + +Each signer's certificate is chain verified using the B<smimesign> purpose and +the supplied trusted certificate store. Any internal certificates in the message +are used as untrusted CAs. If any chain verify fails an error code is returned. + +Finally the signed content is read (and written to B<out> is it is not NULL) and +the signature's checked. + +If all signature's verify correctly then the function is successful. + +Any of the following flags (ored together) can be passed in the B<flags> parameter +to change the default verify behaviour. Only the flag B<PKCS7_NOINTERN> is +meaningful to PKCS7_get0_signers(). + +If B<PKCS7_NOINTERN> is set the certificates in the message itself are not +searched when locating the signer's certificate. This means that all the signers +certificates must be in the B<certs> parameter. + +If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted +from the content. If the content is not of type B<text/plain> then an error is +returned. + +If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified. + +If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are +not used as untrusted CAs. This means that the whole verify chain (apart from +the signer's certificate) must be contained in the trusted store. + +If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked. + +=head1 NOTES + +One application of B<PKCS7_NOINTERN> is to only accept messages signed by +a small number of certificates. The acceptable certificates would be passed +in the B<certs> parameter. In this case if the signer is not one of the +certificates supplied in B<certs> then the verify will fail because the +signer cannot be found. + +Care should be taken when modifying the default verify behaviour, for example +setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification +and any signed message will be considered valid. This combination is however +useful if one merely wishes to write the content to B<out> and its validity +is not considered important. + +Chain verification should arguably be performed using the signing time rather +than the current time. However since the signing time is supplied by the +signer it cannot be trusted without additional evidence (such as a trusted +timestamp). + +=head1 RETURN VALUES + +PKCS7_verify() returns one for a successful verification and zero +if an error occurs. + +PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred. + +The error can be obtained from L<ERR_get_error(3)> + +=head1 BUGS + +The trusted certificate store is not searched for the signers certificate, +this is primarily due to the inadequacies of the current B<X509_STORE> +functionality. + +The lack of single pass processing and need to hold all data in memory as +mentioned in PKCS7_sign() also applies to PKCS7_verify(). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<PKCS7_sign(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RAND_add.pod b/openssl-1.1.0h/doc/crypto/RAND_add.pod new file mode 100644 index 0000000..46de165 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RAND_add.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add +entropy to the PRNG + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + void RAND_seed(const void *buf, int num); + + void RAND_add(const void *buf, int num, double entropy); + + int RAND_status(void); + + #if OPENSSL_API_COMPAT < 0x10100000L + int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); + void RAND_screen(void); + #endif + +=head1 DESCRIPTION + +RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus, +if the data at B<buf> are unpredictable to an adversary, this +increases the uncertainty about the state and makes the PRNG output +less predictable. Suitable input comes from user interaction (random +key presses, mouse movements) and certain hardware events. The +B<entropy> argument is (the lower bound of) an estimate of how much +randomness is contained in B<buf>, measured in bytes. Details about +sources of randomness and how to estimate their entropy can be found +in the literature, e.g. RFC 1750. + +RAND_add() may be called with sensitive data such as user entered +passwords. The seed values cannot be recovered from the PRNG output. + +OpenSSL makes sure that the PRNG state is unique for each thread. On +systems that provide C</dev/urandom>, the randomness device is used +to seed the PRNG transparently. However, on all other systems, the +application is responsible for seeding the PRNG by calling RAND_add(), +L<RAND_egd(3)> +or L<RAND_load_file(3)>. + +RAND_seed() is equivalent to RAND_add() when B<num == entropy>. + +RAND_event() and RAND_screen() are deprecated and should not be called. + +=head1 RETURN VALUES + +RAND_status() returns 1 if the PRNG has been seeded +with enough data, 0 otherwise. + +RAND_event() calls RAND_poll() and returns RAND_status(). + +RAND_screen calls RAND_poll(). + +The other functions do not return values. + +=head1 HISTORY + +RAND_event() and RAND_screen() are deprecated since OpenSSL +1.1.0. Use the functions described above instead. + +=head1 SEE ALSO + +L<rand(3)>, L<RAND_egd(3)>, +L<RAND_load_file(3)>, L<RAND_cleanup(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RAND_bytes.pod b/openssl-1.1.0h/doc/crypto/RAND_bytes.pod new file mode 100644 index 0000000..684215c --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RAND_bytes.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +RAND_bytes, RAND_pseudo_bytes - generate random data + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + int RAND_bytes(unsigned char *buf, int num); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + int RAND_pseudo_bytes(unsigned char *buf, int num); + #endif + +=head1 DESCRIPTION + +RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes +into B<buf>. An error occurs if the PRNG has not been seeded with +enough randomness to ensure an unpredictable byte sequence. + +RAND_pseudo_bytes() has been deprecated. Users should use RAND_bytes() instead. +RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>. +Pseudo-random byte sequences generated by RAND_pseudo_bytes() will be +unique if they are of sufficient length, but are not necessarily +unpredictable. They can be used for non-cryptographic purposes and for +certain purposes in cryptographic protocols, but usually not for key +generation etc. + +The contents of B<buf> is mixed into the entropy pool before retrieving +the new pseudo-random bytes unless disabled at compile time (see FAQ). + +=head1 RETURN VALUES + +RAND_bytes() returns 1 on success, 0 otherwise. The error code can be +obtained by L<ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the +bytes generated are cryptographically strong, 0 otherwise. Both +functions return -1 if they are not supported by the current RAND +method. + +=head1 SEE ALSO + +L<rand(3)>, L<ERR_get_error(3)>, +L<RAND_add(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RAND_cleanup.pod b/openssl-1.1.0h/doc/crypto/RAND_cleanup.pod new file mode 100644 index 0000000..2640c7d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RAND_cleanup.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +RAND_cleanup - erase the PRNG state + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + #if OPENSSL_API_COMPAT < 0x10100000L + void RAND_cleanup(void) + #endif + +=head1 DESCRIPTION + +Prior to OpenSSL 1.1.0 RAND_cleanup() erases the memory used by the PRNG. This +function is deprecated and as of version 1.1.0 does nothing. No explicit +initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>. + +=head1 RETURN VALUE + +RAND_cleanup() returns no value. + +=head1 SEE ALSO + +L<rand(3)> + +=head1 HISTORY + +RAND_cleanup() was deprecated in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RAND_egd.pod b/openssl-1.1.0h/doc/crypto/RAND_egd.pod new file mode 100644 index 0000000..fcc57c0 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RAND_egd.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + int RAND_egd(const char *path); + int RAND_egd_bytes(const char *path, int bytes); + + int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes); + +=head1 DESCRIPTION + +RAND_egd() queries the entropy gathering daemon EGD on socket B<path>. +It queries 255 bytes and uses L<RAND_add(3)> to seed the +OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for +RAND_egd_bytes(path, 255); + +RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>. +It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the +OpenSSL built-in PRNG. +This function is more flexible than RAND_egd(). +When only one secret key must +be generated, it is not necessary to request the full amount 255 bytes from +the EGD socket. This can be advantageous, since the amount of entropy +that can be retrieved from EGD over time is limited. + +RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket +B<path>. If B<buf> is given, B<bytes> bytes are queried and written into +B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the +OpenSSL built-in PRNG using L<RAND_add(3)>. + +=head1 NOTES + +On systems without /dev/*random devices providing entropy from the kernel, +the EGD entropy gathering daemon can be used to collect entropy. It provides +a socket interface through which entropy can be gathered in chunks up to +255 bytes. Several chunks can be queried during one connection. + +EGD is available from http://www.lothar.com/tech/crypto/ (C<perl +Makefile.PL; make; make install> to install). It is run as B<egd> +I<path>, where I<path> is an absolute path designating a socket. When +RAND_egd() is called with that path as an argument, it tries to read +random bytes that EGD has collected. RAND_egd() retrieves entropy from the +daemon using the daemon's "non-blocking read" command which shall +be answered immediately by the daemon without waiting for additional +entropy to be collected. The write and read socket operations in the +communication are blocking. + +Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is +available from +http://prngd.sourceforge.net/ . +PRNGD does employ an internal PRNG itself and can therefore never run +out of entropy. + +OpenSSL automatically queries EGD when entropy is requested via RAND_bytes() +or the status is checked via RAND_status() for the first time, if the socket +is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool. + +=head1 RETURN VALUE + +RAND_egd() and RAND_egd_bytes() return the number of bytes read from the +daemon on success, and -1 if the connection failed or the daemon did not +return enough data to fully seed the PRNG. + +RAND_query_egd_bytes() returns the number of bytes read from the daemon on +success, and -1 if the connection failed. The PRNG state is not considered. + +=head1 SEE ALSO + +L<rand(3)>, L<RAND_add(3)>, +L<RAND_cleanup(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RAND_load_file.pod b/openssl-1.1.0h/doc/crypto/RAND_load_file.pod new file mode 100644 index 0000000..1053a92 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RAND_load_file.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + const char *RAND_file_name(char *buf, size_t num); + + int RAND_load_file(const char *filename, long max_bytes); + + int RAND_write_file(const char *filename); + +=head1 DESCRIPTION + +RAND_file_name() generates a default path for the random seed +file. B<buf> points to a buffer of size B<num> in which to store the +filename. + +On all systems, if the environment variable B<RANDFILE> is set, its +value will be used as the seed file name. + +Otherwise, the file is called ".rnd", found in platform dependent locations: + +=over 4 + +=item On Windows (in order of preference) + +%HOME%, %USERPROFILE%, %SYSTEMROOT%, C:\ + +=item On VMS + +SYS$LOGIN: + +=item On all other systems + +$HOME + +=back + +If C<$HOME> (on non-Windows and non-VMS system) is not set either, or +B<num> is too small for the path name, an error occurs. + +RAND_load_file() reads a number of bytes from file B<filename> and +adds them to the PRNG. If B<max_bytes> is non-negative, +up to B<max_bytes> are read; +if B<max_bytes> is -1, the complete file is read. + +RAND_write_file() writes a number of random bytes (currently 1024) to +file B<filename> which can be used to initialize the PRNG by calling +RAND_load_file() in a later session. + +=head1 RETURN VALUES + +RAND_load_file() returns the number of bytes read or -1 on error. + +RAND_write_file() returns the number of bytes written, and -1 if the +bytes written were generated without appropriate seed. + +RAND_file_name() returns a pointer to B<buf> on success, and NULL on +error. + +=head1 SEE ALSO + +L<rand(3)>, L<RAND_add(3)>, L<RAND_cleanup(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RAND_set_rand_method.pod b/openssl-1.1.0h/doc/crypto/RAND_set_rand_method.pod new file mode 100644 index 0000000..02fe90c --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RAND_set_rand_method.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + void RAND_set_rand_method(const RAND_METHOD *meth); + + const RAND_METHOD *RAND_get_rand_method(void); + + RAND_METHOD *RAND_OpenSSL(void); + +=head1 DESCRIPTION + +A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number +generation. By modifying the method, alternative implementations such as +hardware RNGs may be used. IMPORTANT: See the NOTES section for important +information about how these RAND API functions are affected by the use of +B<ENGINE> API calls. + +Initially, the default RAND_METHOD is the OpenSSL internal implementation, as +returned by RAND_OpenSSL(). + +RAND_set_default_method() makes B<meth> the method for PRNG use. B<NB>: This is +true only whilst no ENGINE has been set as a default for RAND, so this function +is no longer recommended. + +RAND_get_default_method() returns a pointer to the current RAND_METHOD. +However, the meaningfulness of this result is dependent on whether the ENGINE +API is being used, so this function is no longer recommended. + +=head1 THE RAND_METHOD STRUCTURE + + typedef struct rand_meth_st + { + void (*seed)(const void *buf, int num); + int (*bytes)(unsigned char *buf, int num); + void (*cleanup)(void); + void (*add)(const void *buf, int num, int entropy); + int (*pseudorand)(unsigned char *buf, int num); + int (*status)(void); + } RAND_METHOD; + +The components point to method implementations used by (or called by), in order, +RAND_seed(), RAND_bytes(), internal RAND cleanup, RAND_add(), RAND_pseudo_rand() +and RAND_status(). +Each component may be NULL if the function is not implemented. + +=head1 RETURN VALUES + +RAND_set_rand_method() returns no value. RAND_get_rand_method() and +RAND_OpenSSL() return pointers to the respective methods. + +=head1 NOTES + +RAND_METHOD implementations are grouped together with other +algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a +default ENGINE is specified for RAND functionality using an ENGINE API function, +that will override any RAND defaults set using the RAND API (ie. +RAND_set_rand_method()). For this reason, the ENGINE API is the recommended way +to control default implementations for use in RAND and other cryptographic +algorithms. + +=head1 SEE ALSO + +L<rand(3)>, L<engine(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RC4_set_key.pod b/openssl-1.1.0h/doc/crypto/RC4_set_key.pod new file mode 100644 index 0000000..fe5d2d1 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RC4_set_key.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +RC4_set_key, RC4 - RC4 encryption + +=head1 SYNOPSIS + + #include <openssl/rc4.h> + + void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); + + void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, + unsigned char *outdata); + +=head1 DESCRIPTION + +This library implements the Alleged RC4 cipher, which is described for +example in I<Applied Cryptography>. It is believed to be compatible +with RC4[TM], a proprietary cipher of RSA Security Inc. + +RC4 is a stream cipher with variable key length. Typically, 128 bit +(16 byte) keys are used for strong encryption, but shorter insecure +key sizes have been widely used due to export restrictions. + +RC4 consists of a key setup phase and the actual encryption or +decryption phase. + +RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long +key at B<data>. + +RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using +B<key> and places the result at B<outdata>. Repeated RC4() calls with +the same B<key> yield a continuous key stream. + +Since RC4 is a stream cipher (the input is XORed with a pseudo-random +key stream to produce the output), decryption uses the same function +calls as encryption. + +=head1 RETURN VALUES + +RC4_set_key() and RC4() do not return values. + +=head1 NOTE + +Applications should use the higher level functions +L<EVP_EncryptInit(3)> etc. instead of calling these +functions directly. + +It is difficult to securely use stream ciphers. For example, do not perform +multiple encryptions using the same key stream. + +=head1 SEE ALSO + +L<EVP_EncryptInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RIPEMD160_Init.pod b/openssl-1.1.0h/doc/crypto/RIPEMD160_Init.pod new file mode 100644 index 0000000..a372e32 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RIPEMD160_Init.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - +RIPEMD-160 hash function + +=head1 SYNOPSIS + + #include <openssl/ripemd.h> + + unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, + unsigned char *md); + + int RIPEMD160_Init(RIPEMD160_CTX *c); + int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, + unsigned long len); + int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); + +=head1 DESCRIPTION + +RIPEMD-160 is a cryptographic hash function with a +160 bit output. + +RIPEMD160() computes the RIPEMD-160 message digest of the B<n> +bytes at B<d> and places it in B<md> (which must have space for +RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure. + +RIPEMD160_Update() can be called repeatedly with chunks of the message to +be hashed (B<len> bytes at B<data>). + +RIPEMD160_Final() places the message digest in B<md>, which must have +space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases +the B<RIPEMD160_CTX>. + +=head1 RETURN VALUES + +RIPEMD160() returns a pointer to the hash value. + +RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for +success, 0 otherwise. + +=head1 NOTE + +Applications should use the higher level functions +L<EVP_DigestInit(3)> etc. instead of calling these +functions directly. + +=head1 CONFORMING TO + +ISO/IEC 10118-3 (draft) (??) + +=head1 SEE ALSO + +L<EVP_DigestInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_blinding_on.pod b/openssl-1.1.0h/doc/crypto/RSA_blinding_on.pod new file mode 100644 index 0000000..33d49d3 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_blinding_on.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing attacks + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); + + void RSA_blinding_off(RSA *rsa); + +=head1 DESCRIPTION + +RSA is vulnerable to timing attacks. In a setup where attackers can +measure the time of RSA decryption or signature operations, blinding +must be used to protect the RSA operation from that attack. + +RSA_blinding_on() turns blinding on for key B<rsa> and generates a +random blinding factor. B<ctx> is B<NULL> or a pre-allocated and +initialized B<BN_CTX>. The random number generator must be seeded +prior to calling RSA_blinding_on(). + +RSA_blinding_off() turns blinding off and frees the memory used for +the blinding factor. + +=head1 RETURN VALUES + +RSA_blinding_on() returns 1 on success, and 0 if an error occurred. + +RSA_blinding_off() returns no value. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_check_key.pod b/openssl-1.1.0h/doc/crypto/RSA_check_key.pod new file mode 100644 index 0000000..d8689f4 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_check_key.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +RSA_check_key_ex, RSA_check_key - validate private RSA keys + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_check_key_ex(RSA *rsa, BN_GENCB *cb); + + int RSA_check_key(RSA *rsa); + +=head1 DESCRIPTION + +RSA_check_key_ex() function validates RSA keys. +It checks that B<p> and B<q> are +in fact prime, and that B<n = p*q>. + +It does not work on RSA public keys that have only the modulus +and public exponent elements populated. +It also checks that B<d*e = 1 mod (p-1*q-1)>, +and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>. +It performs integrity checks on all +the RSA key material, so the RSA key structure must contain all the private +key data too. +Therefore, it cannot be used with any arbitrary RSA key object, +even if it is otherwise fit for regular RSA operation. + +The B<cb> parameter is a callback that will be invoked in the same +manner as L<BN_is_prime_ex(3)>. + +RSA_check_key() is equivalent to RSA_check_key_ex() with a NULL B<cb>. + +=head1 RETURN VALUE + +RSA_check_key_ex() and RSA_check_key() +return 1 if B<rsa> is a valid RSA key, and 0 otherwise. +They return -1 if an error occurs while checking the key. + +If the key is invalid or an error occurred, the reason code can be +obtained using L<ERR_get_error(3)>. + +=head1 NOTES + +Unlike most other RSA functions, this function does B<not> work +transparently with any underlying ENGINE implementation because it uses the +key data in the RSA structure directly. An ENGINE implementation can +override the way key data is stored and handled, and can even provide +support for HSM keys - in which case the RSA structure may contain B<no> +key data at all! If the ENGINE in question is only being used for +acceleration or analysis purposes, then in all likelihood the RSA key data +is complete and untouched, but this can't be assumed in the general case. + +=head1 BUGS + +A method of verifying the RSA key using opaque RSA API functions might need +to be considered. Right now RSA_check_key() simply uses the RSA structure +elements directly, bypassing the RSA_METHOD table altogether (and +completely violating encapsulation and object-orientation in the process). +The best fix will probably be to introduce a "check_key()" handler to the +RSA_METHOD function table so that alternative implementations can also +provide their own verifiers. + +=head1 SEE ALSO + +L<BN_is_prime_ex(3)>, +L<ERR_get_error(3)> + +=head1 HISTORY + +RSA_check_key_ex() appeared after OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_generate_key.pod b/openssl-1.1.0h/doc/crypto/RSA_generate_key.pod new file mode 100644 index 0000000..e51c0b1 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_generate_key.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +RSA_generate_key_ex, RSA_generate_key - generate RSA key pair + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x00908000L + RSA *RSA_generate_key(int num, unsigned long e, + void (*callback)(int, int, void *), void *cb_arg); + #endif + +=head1 DESCRIPTION + +RSA_generate_key_ex() generates a key pair and stores it in the B<RSA> +structure provided in B<rsa>. The pseudo-random number generator must +be seeded prior to calling RSA_generate_key_ex(). + +The modulus size will be of length B<bits>, and the public exponent will be +B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure. +The exponent is an odd number, typically 3, 17 or 65537. + +A callback function may be used to provide feedback about the +progress of the key generation. If B<cb> is not B<NULL>, it +will be called as follows using the BN_GENCB_call() function +described on the L<BN_generate_prime(3)> page. + +=over 2 + +=item * + +While a random prime number is generated, it is called as +described in L<BN_generate_prime(3)>. + +=item * + +When the n-th randomly generated prime is rejected as not +suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called. + +=item * + +When a random p has been found with p-1 relatively prime to B<e>, +it is called as B<BN_GENCB_call(cb, 3, 0)>. + +=back + +The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>. + +RSA_generate_key() is deprecated (new applications should use +RSA_generate_key_ex() instead). RSA_generate_key() works in the same way as +RSA_generate_key_ex() except it uses "old style" call backs. See +L<BN_generate_prime(3)> for further details. + +=head1 RETURN VALUE + +RSA_generate_key_ex() returns 1 on success or 0 on error. +RSA_generate_key() returns the key on success or B<NULL> on error. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 BUGS + +B<BN_GENCB_call(cb, 2, x)> is used with two different meanings. + +RSA_generate_key() goes into an infinite loop for illegal input values. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<RAND_bytes(3)>, +L<RSA_generate_key(3)>, L<BN_generate_prime(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_get0_key.pod b/openssl-1.1.0h/doc/crypto/RSA_get0_key.pod new file mode 100644 index 0000000..579a2df --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_get0_key.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +RSA_set0_key, RSA_set0_factors, RSA_set0_crt_params, RSA_get0_key, +RSA_get0_factors, RSA_get0_crt_params, RSA_clear_flags, +RSA_test_flags, RSA_set_flags, RSA_get0_engine - Routines for getting +and setting data in an RSA object + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_set0_key(RSA *r, BIGNUM *n, BIGNUM *e, BIGNUM *d); + int RSA_set0_factors(RSA *r, BIGNUM *p, BIGNUM *q); + int RSA_set0_crt_params(RSA *r, BIGNUM *dmp1, BIGNUM *dmq1, BIGNUM *iqmp); + void RSA_get0_key(const RSA *r, + const BIGNUM **n, const BIGNUM **e, const BIGNUM **d); + void RSA_get0_factors(const RSA *r, const BIGNUM **p, const BIGNUM **q); + void RSA_get0_crt_params(const RSA *r, + const BIGNUM **dmp1, const BIGNUM **dmq1, + const BIGNUM **iqmp); + void RSA_clear_flags(RSA *r, int flags); + int RSA_test_flags(const RSA *r, int flags); + void RSA_set_flags(RSA *r, int flags); + ENGINE *RSA_get0_engine(RSA *r); + +=head1 DESCRIPTION + +An RSA object contains the components for the public and private key, +B<n>, B<e>, B<d>, B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp>. B<n> is +the modulus common to both public and private key, B<e> is the public +exponent and B<d> is the private exponent. B<p>, B<q>, B<dmp1>, +B<dmq1> and B<iqmp> are the factors for the second representation of a +private key (see PKCS#1 section 3 Key Types), where B<p> and B<q> are +the first and second factor of B<n> and B<dmp1>, B<dmq1> and B<iqmp> +are the exponents and coefficient for CRT calculations. + +The B<n>, B<e> and B<d> parameters can be obtained by calling +RSA_get0_key(). If they have not been set yet, then B<*n>, B<*e> and +B<*d> will be set to NULL. Otherwise, they are set to pointers to +their respective values. These point directly to the internal +representations of the values and therefore should not be freed +by the caller. + +The B<n>, B<e> and B<d> parameter values can be set by calling +RSA_set0_key() and passing the new values for B<n>, B<e> and B<d> as +parameters to the function. The values B<n> and B<e> must be non-NULL +the first time this function is called on a given RSA object. The +value B<d> may be NULL. On subsequent calls any of these values may be +NULL which means the corresponding RSA field is left untouched. +Calling this function transfers the memory management of the values to +the RSA object, and therefore the values that have been passed in +should not be freed by the caller after this function has been called. + +In a similar fashion, the B<p> and B<q> parameters can be obtained and +set with RSA_get0_factors() and RSA_set0_factors(), and the B<dmp1>, +B<dmq1> and B<iqmp> parameters can be obtained and set with +RSA_get0_crt_params() and RSA_set0_crt_params(). + +For RSA_get0_key(), RSA_get0_factors(), and RSA_get0_crt_params(), +NULL value BIGNUM ** output parameters are permitted. The functions +ignore NULL parameters but return values for other, non-NULL, parameters. + +RSA_set_flags() sets the flags in the B<flags> parameter on the RSA +object. Multiple flags can be passed in one go (bitwise ORed together). +Any flags that are already set are left set. RSA_test_flags() tests to +see whether the flags passed in the B<flags> parameter are currently +set in the RSA object. Multiple flags can be tested in one go. All +flags that are currently set are returned, or zero if none of the +flags are set. RSA_clear_flags() clears the specified flags within the +RSA object. + +RSA_get0_engine() returns a handle to the ENGINE that has been set for +this RSA object, or NULL if no such ENGINE has been set. + +=head1 NOTES + +Values retrieved with RSA_get0_key() are owned by the RSA object used +in the call and may therefore I<not> be passed to RSA_set0_key(). If +needed, duplicate the received value using BN_dup() and pass the +duplicate. The same applies to RSA_get0_factors() and RSA_set0_factors() +as well as RSA_get0_crt_params() and RSA_set0_crt_params(). + +=head1 RETURN VALUES + +RSA_set0_key(), RSA_set0_factors and RSA_set0_crt_params() return 1 on +success or 0 on failure. + +RSA_test_flags() returns the current state of the flags in the RSA object. + +RSA_get0_engine() returns the ENGINE set for the RSA object or NULL if no +ENGINE has been set. + +=head1 SEE ALSO + +L<rsa(3)>, L<RSA_new(3)>, L<RSA_size(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_meth_new.pod b/openssl-1.1.0h/doc/crypto/RSA_meth_new.pod new file mode 100644 index 0000000..9970aa6 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_meth_new.pod @@ -0,0 +1,235 @@ +=pod + +=head1 NAME + +RSA_meth_get0_app_data, RSA_meth_set0_app_data, +RSA_meth_new, RSA_meth_free, RSA_meth_dup, RSA_meth_get0_name, +RSA_meth_set1_name, RSA_meth_get_flags, RSA_meth_set_flags, +RSA_meth_get_pub_enc, +RSA_meth_set_pub_enc, RSA_meth_get_pub_dec, RSA_meth_set_pub_dec, +RSA_meth_get_priv_enc, RSA_meth_set_priv_enc, RSA_meth_get_priv_dec, +RSA_meth_set_priv_dec, RSA_meth_get_mod_exp, RSA_meth_set_mod_exp, +RSA_meth_get_bn_mod_exp, RSA_meth_set_bn_mod_exp, RSA_meth_get_init, +RSA_meth_set_init, RSA_meth_get_finish, RSA_meth_set_finish, +RSA_meth_get_sign, RSA_meth_set_sign, RSA_meth_get_verify, +RSA_meth_set_verify, RSA_meth_get_keygen, RSA_meth_set_keygen +- Routines to build up RSA methods + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + RSA_METHOD *RSA_meth_new(const char *name, int flags); + void RSA_meth_free(RSA_METHOD *meth); + RSA_METHOD *RSA_meth_dup(const RSA_METHOD *meth); + const char *RSA_meth_get0_name(const RSA_METHOD *meth); + int RSA_meth_set1_name(RSA_METHOD *meth, const char *name); + int RSA_meth_get_flags(RSA_METHOD *meth); + int RSA_meth_set_flags(RSA_METHOD *meth, int flags); + void *RSA_meth_get0_app_data(const RSA_METHOD *meth); + int RSA_meth_set0_app_data(RSA_METHOD *meth, void *app_data); + int (*RSA_meth_get_pub_enc(const RSA_METHOD *meth)) + (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_meth_set_pub_enc(RSA_METHOD *rsa, + int (*pub_enc) (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, + int padding)); + int (*RSA_meth_get_pub_dec(const RSA_METHOD *meth)) + (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_meth_set_pub_dec(RSA_METHOD *rsa, + int (*pub_dec) (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, + int padding)); + int (*RSA_meth_get_priv_enc(const RSA_METHOD *meth)) + (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_meth_set_priv_enc(RSA_METHOD *rsa, + int (*priv_enc) (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, + int padding)); + int (*RSA_meth_get_priv_dec(const RSA_METHOD *meth)) + (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_meth_set_priv_dec(RSA_METHOD *rsa, + int (*priv_dec) (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, + int padding)); + /* Can be null */ + int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth)) + (BIGNUM *r0, const BIGNUM *I, RSA *rsa, BN_CTX *ctx); + int RSA_meth_set_mod_exp(RSA_METHOD *rsa, + int (*mod_exp) (BIGNUM *r0, const BIGNUM *I, RSA *rsa, + BN_CTX *ctx)); + /* Can be null */ + int (*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth)) + (BIGNUM *r, const BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); + int RSA_meth_set_bn_mod_exp(RSA_METHOD *rsa, + int (*bn_mod_exp) (BIGNUM *r, + const BIGNUM *a, + const BIGNUM *p, + const BIGNUM *m, + BN_CTX *ctx, + BN_MONT_CTX *m_ctx)); + /* called at new */ + int (*RSA_meth_get_init(const RSA_METHOD *meth)) (RSA *rsa); + int RSA_meth_set_init(RSA_METHOD *rsa, int (*init) (RSA *rsa)); + /* called at free */ + int (*RSA_meth_get_finish(const RSA_METHOD *meth)) (RSA *rsa); + int RSA_meth_set_finish(RSA_METHOD *rsa, int (*finish) (RSA *rsa)); + int (*RSA_meth_get_sign(const RSA_METHOD *meth)) + (int type, + const unsigned char *m, unsigned int m_length, + unsigned char *sigret, unsigned int *siglen, + const RSA *rsa); + int RSA_meth_set_sign(RSA_METHOD *rsa, + int (*sign) (int type, const unsigned char *m, + unsigned int m_length, + unsigned char *sigret, unsigned int *siglen, + const RSA *rsa)); + int (*RSA_meth_get_verify(const RSA_METHOD *meth)) + (int dtype, const unsigned char *m, + unsigned int m_length, const unsigned char *sigbuf, + unsigned int siglen, const RSA *rsa); + int RSA_meth_set_verify(RSA_METHOD *rsa, + int (*verify) (int dtype, const unsigned char *m, + unsigned int m_length, + const unsigned char *sigbuf, + unsigned int siglen, const RSA *rsa)); + int (*RSA_meth_get_keygen(const RSA_METHOD *meth)) + (RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); + int RSA_meth_set_keygen(RSA_METHOD *rsa, + int (*keygen) (RSA *rsa, int bits, BIGNUM *e, + BN_GENCB *cb)); + +=head1 DESCRIPTION + +The B<RSA_METHOD> type is a structure used for the provision of custom +RSA implementations. It provides a set of of functions used by OpenSSL +for the implementation of the various RSA capabilities. See the L<rsa> +page for more information. + +RSA_meth_new() creates a new B<RSA_METHOD> structure. It should be +given a unique B<name> and a set of B<flags>. The B<name> should be a +NULL terminated string, which will be duplicated and stored in the +B<RSA_METHOD> object. It is the callers responsibility to free the +original string. The flags will be used during the construction of a +new B<RSA> object based on this B<RSA_METHOD>. Any new B<RSA> object +will have those flags set by default. + +RSA_meth_dup() creates a duplicate copy of the B<RSA_METHOD> object +passed as a parameter. This might be useful for creating a new +B<RSA_METHOD> based on an existing one, but with some differences. + +RSA_meth_free() destroys an B<RSA_METHOD> structure and frees up any +memory associated with it. + +RSA_meth_get0_name() will return a pointer to the name of this +RSA_METHOD. This is a pointer to the internal name string and so +should not be freed by the caller. RSA_meth_set1_name() sets the name +of the RSA_METHOD to B<name>. The string is duplicated and the copy is +stored in the RSA_METHOD structure, so the caller remains responsible +for freeing the memory associated with the name. + +RSA_meth_get_flags() returns the current value of the flags associated +with this RSA_METHOD. RSA_meth_set_flags() provides the ability to set +these flags. + +The functions RSA_meth_get0_app_data() and RSA_meth_set0_app_data() +provide the ability to associate implementation specific data with the +RSA_METHOD. It is the application's responsibility to free this data +before the RSA_METHOD is freed via a call to RSA_meth_free(). + +RSA_meth_get_sign() and RSA_meth_set_sign() get and set the function +used for creating an RSA signature respectively. This function will be +called in response to the application calling RSA_sign(). The +parameters for the function have the same meaning as for RSA_sign(). + +RSA_meth_get_verify() and RSA_meth_set_verify() get and set the +function used for verifying an RSA signature respectively. This +function will be called in response to the application calling +RSA_verify(). The parameters for the function have the same meaning as +for RSA_verify(). + +RSA_meth_get_mod_exp() and RSA_meth_set_mod_exp() get and set the +function used for CRT computations. + +RSA_meth_get_bn_mod_exp() and RSA_meth_set_bn_mod_exp() get and set +the function used for CRT computations, specifically the following +value: + + r = a ^ p mod m + +Both the mod_exp() and bn_mod_exp() functions are called by the +default OpenSSL method during encryption, decryption, signing and +verification. + +RSA_meth_get_init() and RSA_meth_set_init() get and set the function +used for creating a new RSA instance respectively. This function will +be called in response to the application calling RSA_new() (if the +current default RSA_METHOD is this one) or RSA_new_method(). The +RSA_new() and RSA_new_method() functions will allocate the memory for +the new RSA object, and a pointer to this newly allocated structure +will be passed as a parameter to the function. This function may be +NULL. + +RSA_meth_get_finish() and RSA_meth_set_finish() get and set the +function used for destroying an instance of an RSA object respectively. +This function will be called in response to the application calling +RSA_free(). A pointer to the RSA to be destroyed is passed as a +parameter. The destroy function should be used for RSA implementation +specific clean up. The memory for the RSA itself should not be freed +by this function. This function may be NULL. + +RSA_meth_get_keygen() and RSA_meth_set_keygen() get and set the +function used for generating a new RSA key pair respectively. This +function will be called in response to the application calling +RSA_generate_key(). The parameter for the function has the same +meaning as for RSA_generate_key(). + +RSA_meth_get_pub_enc(), RSA_meth_set_pub_enc(), +RSA_meth_get_pub_dec(), RSA_meth_set_pub_dec(), +RSA_meth_get_priv_enc(), RSA_meth_set_priv_enc(), +RSA_meth_get_priv_dec(), RSA_meth_set_priv_dec() get and set the +functions used for public and private key encryption and decryption. +These functions will be called in response to the application calling +RSA_public_encrypt(), RSA_private_decrypt(), RSA_private_encrypt() and +RSA_public_decrypt() and take the same parameters as those. + + +=head1 RETURN VALUES + +RSA_meth_new() and RSA_meth_dup() return the newly allocated +RSA_METHOD object or NULL on failure. + +RSA_meth_get0_name() and RSA_meth_get_flags() return the name and +flags associated with the RSA_METHOD respectively. + +All other RSA_meth_get_*() functions return the appropriate function +pointer that has been set in the RSA_METHOD, or NULL if no such +pointer has yet been set. + +RSA_meth_set1_name and all RSA_meth_set_*() functions return 1 on +success or 0 on failure. + +=head1 SEE ALSO + +L<RSA_new(3)>, L<RSA_generate_key(3)>, L<RSA_sign(3)>, +L<RSA_set_method(3)>, L<RSA_size(3)>, L<RSA_get0_key(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_new.pod b/openssl-1.1.0h/doc/crypto/RSA_new.pod new file mode 100644 index 0000000..3317920 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_new.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +RSA_new, RSA_free - allocate and free RSA objects + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + RSA * RSA_new(void); + + void RSA_free(RSA *rsa); + +=head1 DESCRIPTION + +RSA_new() allocates and initializes an B<RSA> structure. It is equivalent to +calling RSA_new_method(NULL). + +RSA_free() frees the B<RSA> structure and its components. The key is +erased before the memory is returned to the system. +If B<rsa> is NULL nothing is done. + +=head1 RETURN VALUES + +If the allocation fails, RSA_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns +a pointer to the newly allocated structure. + +RSA_free() returns no value. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<RSA_generate_key(3)>, +L<RSA_new_method(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_padding_add_PKCS1_type_1.pod b/openssl-1.1.0h/doc/crypto/RSA_padding_add_PKCS1_type_1.pod new file mode 100644 index 0000000..5b53eb9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_padding_add_PKCS1_type_1.pod @@ -0,0 +1,129 @@ +=pod + +=head1 NAME + +RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1, +RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2, +RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, +RSA_padding_add_SSLv23, RSA_padding_check_SSLv23, +RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption +padding + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, + unsigned char *f, int fl); + + int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len); + + int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, + unsigned char *f, int fl); + + int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len); + + int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, + unsigned char *f, int fl, unsigned char *p, int pl); + + int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl); + + int RSA_padding_add_SSLv23(unsigned char *to, int tlen, + unsigned char *f, int fl); + + int RSA_padding_check_SSLv23(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len); + + int RSA_padding_add_none(unsigned char *to, int tlen, + unsigned char *f, int fl); + + int RSA_padding_check_none(unsigned char *to, int tlen, + unsigned char *f, int fl, int rsa_len); + +=head1 DESCRIPTION + +The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, +decrypt, sign and verify functions. Normally they should not be called +from application programs. + +However, they can also be called directly to implement padding for other +asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and +RSA_padding_check_PKCS1_OAEP() may be used in an application combined +with B<RSA_NO_PADDING> in order to implement OAEP with an encoding +parameter. + +RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into +B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl> +does not meet the size requirements of the encoding method. + +The following encoding methods are implemented: + +=over 4 + +=item PKCS1_type_1 + +PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures + +=item PKCS1_type_2 + +PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) + +=item PKCS1_OAEP + +PKCS #1 v2.0 EME-OAEP + +=item SSLv23 + +PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification + +=item none + +simply copy the data + +=back + +The random number generator must be seeded prior to calling +RSA_padding_add_xxx(). + +RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain +a valid encoding for a B<rsa_len> byte RSA key in the respective +encoding method and stores the recovered data of at most B<tlen> bytes +(for B<RSA_NO_PADDING>: of size B<tlen>) +at B<to>. + +For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter +of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. + +=head1 RETURN VALUES + +The RSA_padding_add_xxx() functions return 1 on success, 0 on error. +The RSA_padding_check_xxx() functions return the length of the +recovered data, -1 on error. Error codes can be obtained by calling +L<ERR_get_error(3)>. + +=head1 WARNING + +The RSA_padding_check_PKCS1_type_2() padding check leaks timing +information which can potentially be used to mount a Bleichenbacher +padding oracle attack. This is an inherent weakness in the PKCS #1 +v1.5 padding design. Prefer PKCS1_OAEP padding. + +=head1 SEE ALSO + +L<RSA_public_encrypt(3)>, +L<RSA_private_decrypt(3)>, +L<RSA_sign(3)>, L<RSA_verify(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_print.pod b/openssl-1.1.0h/doc/crypto/RSA_print.pod new file mode 100644 index 0000000..1367478 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_print.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +RSA_print, RSA_print_fp, +DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp, +DHparams_print, DHparams_print_fp - print cryptographic parameters + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_print(BIO *bp, RSA *x, int offset); + int RSA_print_fp(FILE *fp, RSA *x, int offset); + + #include <openssl/dsa.h> + + int DSAparams_print(BIO *bp, DSA *x); + int DSAparams_print_fp(FILE *fp, DSA *x); + int DSA_print(BIO *bp, DSA *x, int offset); + int DSA_print_fp(FILE *fp, DSA *x, int offset); + + #include <openssl/dh.h> + + int DHparams_print(BIO *bp, DH *x); + int DHparams_print_fp(FILE *fp, DH *x); + +=head1 DESCRIPTION + +A human-readable hexadecimal output of the components of the RSA +key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>. + +The output lines are indented by B<offset> spaces. + +=head1 RETURN VALUES + +These functions return 1 on success, 0 on error. + +=head1 SEE ALSO + +L<BN_bn2bin(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_private_encrypt.pod b/openssl-1.1.0h/doc/crypto/RSA_private_encrypt.pod new file mode 100644 index 0000000..1eb7a0a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_private_encrypt.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +RSA_private_encrypt, RSA_public_decrypt - low level signature operations + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_private_encrypt(int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + int RSA_public_decrypt(int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + +=head1 DESCRIPTION + +These functions handle RSA signatures at a low level. + +RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a +message digest with an algorithm identifier) using the private key +B<rsa> and stores the signature in B<to>. B<to> must point to +B<RSA_size(rsa)> bytes of memory. + +B<padding> denotes one of the following modes: + +=over 4 + +=item RSA_PKCS1_PADDING + +PKCS #1 v1.5 padding. This function does not handle the +B<algorithmIdentifier> specified in PKCS #1. When generating or +verifying PKCS #1 signatures, L<RSA_sign(3)> and L<RSA_verify(3)> should be +used. + +=item RSA_NO_PADDING + +Raw RSA signature. This mode should I<only> be used to implement +cryptographically sound padding modes in the application code. +Signing user data directly with RSA is insecure. + +=back + +RSA_public_decrypt() recovers the message digest from the B<flen> +bytes long signature at B<from> using the signer's public key +B<rsa>. B<to> must point to a memory section large enough to hold the +message digest (which is smaller than B<RSA_size(rsa) - +11>). B<padding> is the padding mode that was used to sign the data. + +=head1 RETURN VALUES + +RSA_private_encrypt() returns the size of the signature (i.e., +RSA_size(rsa)). RSA_public_decrypt() returns the size of the +recovered message digest. + +On error, -1 is returned; the error codes can be +obtained by L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<RSA_sign(3)>, L<RSA_verify(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_public_encrypt.pod b/openssl-1.1.0h/doc/crypto/RSA_public_encrypt.pod new file mode 100644 index 0000000..b1dd50d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_public_encrypt.pod @@ -0,0 +1,95 @@ +=pod + +=head1 NAME + +RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_public_encrypt(int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + int RSA_private_decrypt(int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + +=head1 DESCRIPTION + +RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a +session key) using the public key B<rsa> and stores the ciphertext in +B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory. + +B<padding> denotes one of the following modes: + +=over 4 + +=item RSA_PKCS1_PADDING + +PKCS #1 v1.5 padding. This currently is the most widely used mode. + +=item RSA_PKCS1_OAEP_PADDING + +EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty +encoding parameter. This mode is recommended for all new applications. + +=item RSA_SSLV23_PADDING + +PKCS #1 v1.5 padding with an SSL-specific modification that denotes +that the server is SSL3 capable. + +=item RSA_NO_PADDING + +Raw RSA encryption. This mode should I<only> be used to implement +cryptographically sound padding modes in the application code. +Encrypting user data directly with RSA is insecure. + +=back + +B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 +based padding modes, less than RSA_size(B<rsa>) - 41 for +RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING. +The random number generator must be seeded prior to calling +RSA_public_encrypt(). + +RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the +private key B<rsa> and stores the plaintext in B<to>. B<to> must point +to a memory section large enough to hold the decrypted data (which is +smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that +was used to encrypt the data. + +=head1 RETURN VALUES + +RSA_public_encrypt() returns the size of the encrypted data (i.e., +RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the +recovered plaintext. + +On error, -1 is returned; the error codes can be +obtained by L<ERR_get_error(3)>. + +=head1 WARNING + +Decryption failures in the RSA_PKCS1_PADDING mode leak information +which can potentially be used to mount a Bleichenbacher padding oracle +attack. This is an inherent weakness in the PKCS #1 v1.5 padding +design. Prefer RSA_PKCS1_OAEP_PADDING. + +=head1 CONFORMING TO + +SSL, PKCS #1 v2.0 + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<rand(3)>, +L<RSA_size(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_set_method.pod b/openssl-1.1.0h/doc/crypto/RSA_set_method.pod new file mode 100644 index 0000000..668ad7a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_set_method.pod @@ -0,0 +1,186 @@ +=pod + +=head1 NAME + +RSA_set_default_method, RSA_get_default_method, RSA_set_method, +RSA_get_method, RSA_PKCS1_OpenSSL, RSA_flags, +RSA_new_method - select RSA method + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + void RSA_set_default_method(const RSA_METHOD *meth); + + RSA_METHOD *RSA_get_default_method(void); + + int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); + + RSA_METHOD *RSA_get_method(const RSA *rsa); + + RSA_METHOD *RSA_PKCS1_OpenSSL(void); + + int RSA_flags(const RSA *rsa); + + RSA *RSA_new_method(ENGINE *engine); + +=head1 DESCRIPTION + +An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA +operations. By modifying the method, alternative implementations such as +hardware accelerators may be used. IMPORTANT: See the NOTES section for +important information about how these RSA API functions are affected by the +use of B<ENGINE> API calls. + +Initially, the default RSA_METHOD is the OpenSSL internal implementation, +as returned by RSA_PKCS1_OpenSSL(). + +RSA_set_default_method() makes B<meth> the default method for all RSA +structures created later. +B<NB>: This is true only whilst no ENGINE has +been set as a default for RSA, so this function is no longer recommended. +This function is not thread-safe and should not be called at the same time +as other OpenSSL functions. + +RSA_get_default_method() returns a pointer to the current default +RSA_METHOD. However, the meaningfulness of this result is dependent on +whether the ENGINE API is being used, so this function is no longer +recommended. + +RSA_set_method() selects B<meth> to perform all operations using the key +B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the +previous method was supplied by an ENGINE, the handle to that ENGINE will +be released during the change. It is possible to have RSA keys that only +work with certain RSA_METHOD implementations (eg. from an ENGINE module +that supports embedded hardware-protected keys), and in such cases +attempting to change the RSA_METHOD for the key can have unexpected +results. + +RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>. +This method may or may not be supplied by an ENGINE implementation, but if +it is, the return value can only be guaranteed to be valid as long as the +RSA key itself is valid and does not have its implementation changed by +RSA_set_method(). + +RSA_flags() returns the B<flags> that are set for B<rsa>'s current +RSA_METHOD. See the BUGS section. + +RSA_new_method() allocates and initializes an RSA structure so that +B<engine> will be used for the RSA operations. If B<engine> is NULL, the +default ENGINE for RSA operations is used, and if no default ENGINE is set, +the RSA_METHOD controlled by RSA_set_default_method() is used. + +RSA_flags() returns the B<flags> that are set for B<rsa>'s current method. + +RSA_new_method() allocates and initializes an B<RSA> structure so that +B<method> will be used for the RSA operations. If B<method> is B<NULL>, +the default method is used. + +=head1 THE RSA_METHOD STRUCTURE + + typedef struct rsa_meth_st + { + /* name of the implementation */ + const char *name; + + /* encrypt */ + int (*rsa_pub_enc)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* verify arbitrary data */ + int (*rsa_pub_dec)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* sign arbitrary data */ + int (*rsa_priv_enc)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* decrypt */ + int (*rsa_priv_dec)(int flen, unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + + /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some + implementations) */ + int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); + + /* compute r = a ^ p mod m (May be NULL for some implementations) */ + int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); + + /* called at RSA_new */ + int (*init)(RSA *rsa); + + /* called at RSA_free */ + int (*finish)(RSA *rsa); + + /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key + * operations, even if p,q,dmp1,dmq1,iqmp + * are NULL + * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match + */ + int flags; + + char *app_data; /* ?? */ + + int (*rsa_sign)(int type, + const unsigned char *m, unsigned int m_length, + unsigned char *sigret, unsigned int *siglen, const 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; + +=head1 RETURN VALUES + +RSA_PKCS1_OpenSSL(), RSA_PKCS1_null_method(), RSA_get_default_method() +and RSA_get_method() return pointers to the respective RSA_METHODs. + +RSA_set_default_method() returns no value. + +RSA_set_method() returns a pointer to the old RSA_METHOD implementation +that was replaced. However, this return value should probably be ignored +because if it was supplied by an ENGINE, the pointer could be invalidated +at any time if the ENGINE is unloaded (in fact it could be unloaded as a +result of the RSA_set_method() function releasing its handle to the +ENGINE). For this reason, the return type may be replaced with a B<void> +declaration in a future release. + +RSA_new_method() returns NULL and sets an error code that can be obtained +by L<ERR_get_error(3)> if the allocation fails. Otherwise +it returns a pointer to the newly allocated structure. + +=head1 BUGS + +The behaviour of RSA_flags() is a mis-feature that is left as-is for now +to avoid creating compatibility problems. RSA functionality, such as the +encryption functions, are controlled by the B<flags> value in the RSA key +itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key +(which is what this function returns). If the flags element of an RSA key +is changed, the changes will be honoured by RSA functionality but will not +be reflected in the return value of the RSA_flags() function - in effect +RSA_flags() behaves more like an RSA_default_flags() function (which does +not currently exist). + +=head1 SEE ALSO + +L<RSA_new(3)> + +=head1 HISTORY + +The RSA_null_method(), which was a partial attempt to avoid patent issues, +was replaced to always return NULL in OpenSSL 1.1.0f. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_sign.pod b/openssl-1.1.0h/doc/crypto/RSA_sign.pod new file mode 100644 index 0000000..fbb38d8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_sign.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +RSA_sign, RSA_verify - RSA signatures + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_sign(int type, const unsigned char *m, unsigned int m_len, + unsigned char *sigret, unsigned int *siglen, RSA *rsa); + + int RSA_verify(int type, const unsigned char *m, unsigned int m_len, + unsigned char *sigbuf, unsigned int siglen, RSA *rsa); + +=head1 DESCRIPTION + +RSA_sign() signs the message digest B<m> of size B<m_len> using the +private key B<rsa> using RSASSA-PKCS1-v1_5 as specified in RFC 3447. 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)> for lower-level +operations. + +B<type> denotes the message digest algorithm that was used to generate +B<m>. +If B<type> is B<NID_md5_sha1>, +an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding +and no algorithm identifier) is created. + +RSA_verify() verifies that the signature B<sigbuf> of size B<siglen> +matches a given message digest B<m> of size B<m_len>. B<type> denotes +the message digest algorithm that was used to generate the signature. +B<rsa> is the signer's public key. + +=head1 RETURN VALUES + +RSA_sign() returns 1 on success. +RSA_verify() returns 1 on successful verification. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 CONFORMING TO + +SSL, PKCS #1 v2.0 + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<RSA_private_encrypt(3)>, +L<RSA_public_decrypt(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/openssl-1.1.0h/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod new file mode 100644 index 0000000..16303c9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, + unsigned int m_len, unsigned char *sigret, unsigned int *siglen, + RSA *rsa); + + int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, + unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, + RSA *rsa); + +=head1 DESCRIPTION + +RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size +B<m_len> using the private key B<rsa> represented in DER using PKCS #1 +padding. It stores the signature in B<sigret> and the signature size +in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of +memory. + +B<dummy> is ignored. + +The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING(). + +RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf> +of size B<siglen> is the DER representation of a given octet string +B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's +public key. + +=head1 RETURN VALUES + +RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise. +RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0 +otherwise. + +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 BUGS + +These functions serve no recognizable purpose. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<rand(3)>, L<RSA_sign(3)>, +L<RSA_verify(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/RSA_size.pod b/openssl-1.1.0h/doc/crypto/RSA_size.pod new file mode 100644 index 0000000..eb6e481 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/RSA_size.pod @@ -0,0 +1,46 @@ +=pod + +=head1 NAME + +RSA_size, RSA_bits - get RSA modulus size + +=head1 SYNOPSIS + +#include <openssl/rsa.h> + +int RSA_size(const RSA *rsa); + +int RSA_bits(const RSA *rsa); + +=head1 DESCRIPTION + +RSA_size() returns the RSA modulus size in bytes. It can be used to +determine how much memory must be allocated for an RSA encrypted +value. + +RSA_bits() returns the number of significant bits. + +B<rsa> and B<rsa-E<gt>n> must not be B<NULL>. + +=head1 RETURN VALUE + +The size. + +=head1 SEE ALSO + +L<BN_num_bits(3)> + +=head1 HISTORY + +RSA_bits() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SCT_new.pod b/openssl-1.1.0h/doc/crypto/SCT_new.pod new file mode 100644 index 0000000..fb395a5 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SCT_new.pod @@ -0,0 +1,194 @@ +=pod + +=head1 NAME + +SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free, +SCT_get_version, SCT_set_version, +SCT_get_log_entry_type, SCT_set_log_entry_type, +SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id, +SCT_get_timestamp, SCT_set_timestamp, +SCT_get_signature_nid, SCT_set_signature_nid, +SCT_get0_signature, SCT_set0_signature, SCT_set1_signature, +SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions, +SCT_get_source, SCT_set_source +- A Certificate Transparency Signed Certificate Timestamp + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + typedef enum { + CT_LOG_ENTRY_TYPE_NOT_SET = -1, + CT_LOG_ENTRY_TYPE_X509 = 0, + CT_LOG_ENTRY_TYPE_PRECERT = 1 + } ct_log_entry_type_t; + + typedef enum { + SCT_VERSION_NOT_SET = -1, + SCT_VERSION_V1 = 0 + } sct_version_t; + + typedef enum { + SCT_SOURCE_UNKNOWN, + SCT_SOURCE_TLS_EXTENSION, + SCT_SOURCE_X509V3_EXTENSION, + SCT_SOURCE_OCSP_STAPLED_RESPONSE + } sct_source_t; + + SCT *SCT_new(void); + SCT *SCT_new_from_base64(unsigned char version, + const char *logid_base64, + ct_log_entry_type_t entry_type, + uint64_t timestamp, + const char *extensions_base64, + const char *signature_base64); + + void SCT_free(SCT *sct); + void SCT_LIST_free(STACK_OF(SCT) *a); + + sct_version_t SCT_get_version(const SCT *sct); + int SCT_set_version(SCT *sct, sct_version_t version); + + ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct); + int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type); + + size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id); + int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len); + int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len); + + uint64_t SCT_get_timestamp(const SCT *sct); + void SCT_set_timestamp(SCT *sct, uint64_t timestamp); + + int SCT_get_signature_nid(const SCT *sct); + int SCT_set_signature_nid(SCT *sct, int nid); + + size_t SCT_get0_signature(const SCT *sct, unsigned char **sig); + void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len); + int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len); + + size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext); + void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len); + int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len); + + sct_source_t SCT_get_source(const SCT *sct); + int SCT_set_source(SCT *sct, sct_source_t source); + +=head1 DESCRIPTION + +Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2. +They constitute a promise by a Certificate Transparency (CT) log to publicly +record a certificate. By cryptographically verifying that a log did indeed issue +an SCT, some confidence can be gained that the certificate is publicly known. + +An internal representation of an SCT can be created in one of two ways. +The first option is to create a blank SCT, using SCT_new(), and then populate +it using: + +=over 4 + +=item * SCT_set_version() to set the SCT version. + +Only SCT_VERSION_V1 is currently supported. + +=item * SCT_set_log_entry_type() to set the type of certificate the SCT was issued for: + +B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate. +B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate. + +=item * SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from. + +The former takes ownership, whereas the latter makes a copy. +See RFC 6962, Section 3.2 for the definition of LogID. + +=item * SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds). + +=item * SCT_set_signature_nid() to set the NID of the signature. + +=item * SCT_set0_signature() or SCT_set1_signature() to set the raw signature value. + +The former takes ownership, whereas the latter makes a copy. + +=item * SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions. + +The former takes ownership, whereas the latter makes a copy. + +=back + +Alternatively, the SCT can be pre-populated from the following data using +SCT_new_from_base64(): + +=over 4 + +=item * The SCT version (only SCT_VERSION_V1 is currently supported). + +=item * The LogID (see RFC 6962, Section 3.2), base64 encoded. + +=item * The type of certificate the SCT was issued for: + +B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate. +B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate. + +=item * The time that the SCT was issued (epoch time in milliseconds). + +=item * The SCT extensions, base64 encoded. + +=item * The SCT signature, base64 encoded. + +=back + +SCT_set_source() can be used to record where the SCT was found +(TLS extension, X.509 certificate extension or OCSP response). This is not +required for verifying the SCT. + +=head1 NOTES + +Some of the setters return int, instead of void. These will all return 1 on +success, 0 on failure. They will not make changes on failure. + +All of the setters will reset the validation status of the SCT to +SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_validate(3)>). + +SCT_set_source() will call SCT_set_log_entry_type() if the type of +certificate the SCT was issued for can be inferred from where the SCT was found. +For example, an SCT found in an X.509 extension must have been issued for a pre- +certificate. + +SCT_set_source() will not refuse unknown values. + +=head1 RETURN VALUES + +SCT_set_version() returns 1 if the specified version is supported, 0 otherwise. + +SCT_set_log_entry_type() returns 1 if the specified log entry type is supported, 0 otherwise. + +SCT_set0_log_id() and B<SCT_set1_log_id> return 1 if the specified LogID is a +valid SHA-256 hash, 0 otherwise. Additionally, B<SCT_set1_log_id> returns 0 if +malloc fails. + +B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise. + +B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer +is copied successfully, 0 otherwise (i.e. if malloc fails). + +B<SCT_set_source> returns 1 on success, 0 otherwise. + +=head1 SEE ALSO + +L<ct(7)>, +L<SCT_validate(3)>, +L<OBJ_nid2obj(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SCT_print.pod b/openssl-1.1.0h/doc/crypto/SCT_print.pod new file mode 100644 index 0000000..88ad43e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SCT_print.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SCT_print, SCT_LIST_print, SCT_validation_status_string - +Prints Signed Certificate Timestamps in a human-readable way + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + void SCT_print(const SCT *sct, BIO *out, int indent, const CTLOG_STORE *logs); + void SCT_LIST_print(const STACK_OF(SCT) *sct_list, BIO *out, int indent, + const char *separator, const CTLOG_STORE *logs); + const char *SCT_validation_status_string(const SCT *sct); + +=head1 DESCRIPTION + +SCT_print() prints a single Signed Certificate Timestamp (SCT) to a L<bio> in +a human-readable format. SCT_LIST_print() prints an entire list of SCTs in a +similar way. A separator can be specified to delimit each SCT in the output. + +The output can be indented by a specified number of spaces. If a B<CTLOG_STORE> +is provided, it will be used to print the description of the CT log that issued +each SCT (if that log is in the CTLOG_STORE). Alternatively, NULL can be passed +as the CTLOG_STORE parameter to disable this feature. + +SCT_validation_status_string() will return the validation status of an SCT as +a human-readable string. Call SCT_validate() or SCT_LIST_validate() +beforehand in order to set the validation status of an SCT first. + +=head1 SEE ALSO + +L<ct(3)>, +L<bio(3)>, +L<CTLOG_STORE_new(3)>, +L<SCT_validate(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SCT_validate.pod b/openssl-1.1.0h/doc/crypto/SCT_validate.pod new file mode 100644 index 0000000..3c03e97 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SCT_validate.pod @@ -0,0 +1,98 @@ +=pod + +=head1 NAME + +SCT_validate, SCT_LIST_validate, SCT_get_validation_status - +checks Signed Certificate Timestamps (SCTs) are valid + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + typedef enum { + SCT_VALIDATION_STATUS_NOT_SET, + SCT_VALIDATION_STATUS_UNKNOWN_LOG, + SCT_VALIDATION_STATUS_VALID, + SCT_VALIDATION_STATUS_INVALID, + SCT_VALIDATION_STATUS_UNVERIFIED, + SCT_VALIDATION_STATUS_UNKNOWN_VERSION + } sct_validation_status_t; + + int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx); + int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx); + sct_validation_status_t SCT_get_validation_status(const SCT *sct); + +=head1 DESCRIPTION + +SCT_validate() will check that an SCT is valid and verify its signature. +SCT_LIST_validate() performs the same checks on an entire stack of SCTs. +The result of the validation checks can be obtained by passing the SCT to +SCT_get_validation_status(). + +A CT_POLICY_EVAL_CTX must be provided that specifies: + +=over 4 + +=item * The certificate the SCT was issued for. + +Failure to provide the certificate will result in the validation status being +SCT_VALIDATION_STATUS_UNVERIFIED. + +=item * The issuer of that certificate. + +This is only required if the SCT was issued for a pre-certificate +(see RFC 6962). If it is required but not provided, the validation status will +be SCT_VALIDATION_STATUS_UNVERIFIED. + +=item * A CTLOG_STORE that contains the CT log that issued this SCT. + +If the SCT was issued by a log that is not in this CTLOG_STORE, the validation +status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG. + +=back + +If the SCT is of an unsupported version (only v1 is currently supported), the +validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION. + +If the SCT's signature is incorrect, its timestamp is in the future (relative to +the time in CT_POLICY_EVAL_CTX), or if it is otherwise invalid, the validation +status will be SCT_VALIDATION_STATUS_INVALID. + +If all checks pass, the validation status will be SCT_VALIDATION_STATUS_VALID. + +=head1 NOTES + +A return value of 0 from SCT_LIST_validate() should not be interpreted as a +failure. At a minimum, only one valid SCT may provide sufficient confidence +that a certificate has been publicly logged. + +=head1 RETURN VALUES + +SCT_validate() returns a negative integer if an internal error occurs, 0 if the +SCT fails validation, or 1 if the SCT passes validation. + +SCT_LIST_validate() returns a negative integer if an internal error occurs, 0 +if any of SCTs fails validation, or 1 if they all pass validation. + +SCT_get_validation_status() returns the validation status of the SCT. +If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the +returned value will be SCT_VALIDATION_STATUS_NOT_SET. + +=head1 SEE ALSO + +L<ct(7)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SHA256_Init.pod b/openssl-1.1.0h/doc/crypto/SHA256_Init.pod new file mode 100644 index 0000000..f3565bb --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SHA256_Init.pod @@ -0,0 +1,108 @@ +=pod + +=head1 NAME + +SHA1, SHA1_Init, SHA1_Update, SHA1_Final, SHA224, SHA224_Init, SHA224_Update, +SHA224_Final, SHA256, SHA256_Init, SHA256_Update, SHA256_Final, SHA384, +SHA384_Init, SHA384_Update, SHA384_Final, SHA512, SHA512_Init, SHA512_Update, +SHA512_Final - Secure Hash Algorithm + +=head1 SYNOPSIS + + #include <openssl/sha.h> + + int SHA1_Init(SHA_CTX *c); + int SHA1_Update(SHA_CTX *c, const void *data, size_t len); + int SHA1_Final(unsigned char *md, SHA_CTX *c); + unsigned char *SHA1(const unsigned char *d, size_t n, + unsigned char *md); + + int SHA224_Init(SHA256_CTX *c); + int SHA224_Update(SHA256_CTX *c, const void *data, size_t len); + int SHA224_Final(unsigned char *md, SHA256_CTX *c); + unsigned char *SHA224(const unsigned char *d, size_t n, + unsigned char *md); + + int SHA256_Init(SHA256_CTX *c); + int SHA256_Update(SHA256_CTX *c, const void *data, size_t len); + int SHA256_Final(unsigned char *md, SHA256_CTX *c); + unsigned char *SHA256(const unsigned char *d, size_t n, + unsigned char *md); + + int SHA384_Init(SHA512_CTX *c); + int SHA384_Update(SHA512_CTX *c, const void *data, size_t len); + int SHA384_Final(unsigned char *md, SHA512_CTX *c); + unsigned char *SHA384(const unsigned char *d, size_t n, + unsigned char *md); + + int SHA512_Init(SHA512_CTX *c); + int SHA512_Update(SHA512_CTX *c, const void *data, size_t len); + int SHA512_Final(unsigned char *md, SHA512_CTX *c); + unsigned char *SHA512(const unsigned char *d, size_t n, + unsigned char *md); + +=head1 DESCRIPTION + +Applications should use the higher level functions +L<EVP_DigestInit(3)> etc. instead of calling the hash +functions directly. + +SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a +160 bit output. + +SHA1() computes the SHA-1 message digest of the B<n> +bytes at B<d> and places it in B<md> (which must have space for +SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest +is placed in a static array. Note: setting B<md> to NULL is B<not thread safe>. + +The following functions may be used if the message is not completely +stored in memory: + +SHA1_Init() initializes a B<SHA_CTX> structure. + +SHA1_Update() can be called repeatedly with chunks of the message to +be hashed (B<len> bytes at B<data>). + +SHA1_Final() places the message digest in B<md>, which must have space +for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>. + +The SHA224, SHA256, SHA384 and SHA512 families of functions operate in the +same way as for the SHA1 functions. Note that SHA224 and SHA256 use a +B<SHA256_CTX> object instead of B<SHA_CTX>. SHA384 and SHA512 use B<SHA512_CTX>. +The buffer B<md> must have space for the output from the SHA variant being used +(defined by SHA224_DIGEST_LENGTH, SHA256_DIGEST_LENGTH, SHA384_DIGEST_LENGTH and +SHA512_DIGEST_LENGTH). Also note that, as for the SHA1() function above, the +SHA224(), SHA256(), SHA384() and SHA512() functions are not thread safe if +B<md> is NULL. + +The predecessor of SHA-1, SHA, is also implemented, but it should be +used only when backward compatibility is required. + +=head1 RETURN VALUES + +SHA1(), SHA224(), SHA256(), SHA384() and SHA512() return a pointer to the hash +value. + +SHA1_Init(), SHA1_Update() and SHA1_Final() and equivalent SHA224, SHA256, +SHA384 and SHA512 functions return 1 for success, 0 otherwise. + +=head1 CONFORMING TO + +US Federal Information Processing Standard FIPS PUB 180-4 (Secure Hash +Standard), +ANSI X9.30 + +=head1 SEE ALSO + +L<EVP_DigestInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SMIME_read_CMS.pod b/openssl-1.1.0h/doc/crypto/SMIME_read_CMS.pod new file mode 100644 index 0000000..efde0bd --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SMIME_read_CMS.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + +SMIME_read_CMS - parse S/MIME message + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont); + +=head1 DESCRIPTION + +SMIME_read_CMS() parses a message in S/MIME format. + +B<in> is a BIO to read the message from. + +If cleartext signing is used then the content is saved in a memory bio which is +written to B<*bcont>, otherwise B<*bcont> is set to NULL. + +The parsed CMS_ContentInfo structure is returned or NULL if an +error occurred. + +=head1 NOTES + +If B<*bcont> is not NULL then the message is clear text signed. B<*bcont> can +then be passed to CMS_verify() with the B<CMS_DETACHED> flag set. + +Otherwise the type of the returned structure can be determined +using CMS_get0_type(). + +To support future functionality if B<bcont> is not NULL B<*bcont> should be +initialized to NULL. For example: + + BIO *cont = NULL; + CMS_ContentInfo *cms; + + cms = SMIME_read_CMS(in, &cont); + +=head1 BUGS + +The MIME parser used by SMIME_read_CMS() is somewhat primitive. While it will +handle most S/MIME messages more complex compound formats may not work. + +The parser assumes that the CMS_ContentInfo structure is always base64 encoded +and will not handle the case where it is in binary format or uses quoted +printable format. + +The use of a memory BIO to hold the signed content limits the size of message +which can be processed due to memory restraints: a streaming single pass option +should be available. + +=head1 RETURN VALUES + +SMIME_read_CMS() returns a valid B<CMS_ContentInfo> structure or B<NULL> +if an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_type(3)> +L<SMIME_read_CMS(3)>, L<CMS_sign(3)>, +L<CMS_verify(3)>, L<CMS_encrypt(3)> +L<CMS_decrypt(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SMIME_read_PKCS7.pod b/openssl-1.1.0h/doc/crypto/SMIME_read_PKCS7.pod new file mode 100644 index 0000000..3eb8bbc --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SMIME_read_PKCS7.pod @@ -0,0 +1,78 @@ +=pod + +=head1 NAME + +SMIME_read_PKCS7 - parse S/MIME message + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont); + +=head1 DESCRIPTION + +SMIME_read_PKCS7() parses a message in S/MIME format. + +B<in> is a BIO to read the message from. + +If cleartext signing is used then the content is saved in +a memory bio which is written to B<*bcont>, otherwise +B<*bcont> is set to B<NULL>. + +The parsed PKCS#7 structure is returned or B<NULL> if an +error occurred. + +=head1 NOTES + +If B<*bcont> is not B<NULL> then the message is clear text +signed. B<*bcont> can then be passed to PKCS7_verify() with +the B<PKCS7_DETACHED> flag set. + +Otherwise the type of the returned structure can be determined +using PKCS7_type_is_enveloped(), etc. + +To support future functionality if B<bcont> is not B<NULL> +B<*bcont> should be initialized to B<NULL>. For example: + + BIO *cont = NULL; + PKCS7 *p7; + + p7 = SMIME_read_PKCS7(in, &cont); + +=head1 BUGS + +The MIME parser used by SMIME_read_PKCS7() is somewhat primitive. +While it will handle most S/MIME messages more complex compound +formats may not work. + +The parser assumes that the PKCS7 structure is always base64 +encoded and will not handle the case where it is in binary format +or uses quoted printable format. + +The use of a memory BIO to hold the signed content limits the size +of message which can be processed due to memory restraints: a +streaming single pass option should be available. + +=head1 RETURN VALUES + +SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL> +is an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L<ERR_get_error(3)>, +L<SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)>, +L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)> + +=head1 COPYRIGHT + +Copyright 2002-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SMIME_write_CMS.pod b/openssl-1.1.0h/doc/crypto/SMIME_write_CMS.pod new file mode 100644 index 0000000..d58baeb --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SMIME_write_CMS.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +SMIME_write_CMS - convert CMS structure to S/MIME format + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); + +=head1 DESCRIPTION + +SMIME_write_CMS() adds the appropriate MIME headers to a CMS +structure to produce an S/MIME message. + +B<out> is the BIO to write the data to. B<cms> is the appropriate +B<CMS_ContentInfo> structure. If streaming is enabled then the content must be +supplied in the B<data> argument. B<flags> is an optional set of flags. + +=head1 NOTES + +The following flags can be passed in the B<flags> parameter. + +If B<CMS_DETACHED> is set then cleartext signing will be used, this option only +makes sense for SignedData where B<CMS_DETACHED> is also set when CMS_sign() is +called. + +If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are added to +the content, this only makes sense if B<CMS_DETACHED> is also set. + +If the B<CMS_STREAM> flag is set streaming is performed. This flag should only +be set if B<CMS_STREAM> was also set in the previous call to a CMS_ContentInfo +creation function. + +If cleartext signing is being used and B<CMS_STREAM> not set then the data must +be read twice: once to compute the signature in CMS_sign() and once to output +the S/MIME message. + +If streaming is performed the content is output in BER format using indefinite +length constructed encoding except in the case of signed data with detached +content where the content is absent and DER format is used. + +=head1 BUGS + +SMIME_write_CMS() always base64 encodes CMS structures, there should be an +option to disable this. + +=head1 RETURN VALUES + +SMIME_write_CMS() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_verify(3)>, L<CMS_encrypt(3)> +L<CMS_decrypt(3)> + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SMIME_write_PKCS7.pod b/openssl-1.1.0h/doc/crypto/SMIME_write_PKCS7.pod new file mode 100644 index 0000000..b573123 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SMIME_write_PKCS7.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags); + +=head1 DESCRIPTION + +SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7 +structure to produce an S/MIME message. + +B<out> is the BIO to write the data to. B<p7> is the appropriate B<PKCS7> +structure. If streaming is enabled then the content must be supplied in the +B<data> argument. B<flags> is an optional set of flags. + +=head1 NOTES + +The following flags can be passed in the B<flags> parameter. + +If B<PKCS7_DETACHED> is set then cleartext signing will be used, +this option only makes sense for signedData where B<PKCS7_DETACHED> +is also set when PKCS7_sign() is also called. + +If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> +are added to the content, this only makes sense if B<PKCS7_DETACHED> +is also set. + +If the B<PKCS7_STREAM> flag is set streaming is performed. This flag should +only be set if B<PKCS7_STREAM> was also set in the previous call to +PKCS7_sign() or PKCS7_encrypt(). + +If cleartext signing is being used and B<PKCS7_STREAM> not set then +the data must be read twice: once to compute the signature in PKCS7_sign() +and once to output the S/MIME message. + +If streaming is performed the content is output in BER format using indefinite +length constructed encoding except in the case of signed data with detached +content where the content is absent and DER format is used. + +=head1 BUGS + +SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there +should be an option to disable this. + +=head1 RETURN VALUES + +SMIME_write_PKCS7() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<PKCS7_sign(3)>, +L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/SSL_CTX_set_tlsext_use_srtp.pod b/openssl-1.1.0h/doc/crypto/SSL_CTX_set_tlsext_use_srtp.pod new file mode 100644 index 0000000..2746d50 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/SSL_CTX_set_tlsext_use_srtp.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tlsext_use_srtp, +SSL_set_tlsext_use_srtp, +SSL_get_srtp_profiles, +SSL_get_selected_srtp_profile +- Configure and query SRTP support + +=head1 SYNOPSIS + + #include <openssl/srtp.h> + + int SSL_CTX_set_tlsext_use_srtp(SSL_CTX *ctx, const char *profiles); + int SSL_set_tlsext_use_srtp(SSL *ssl, const char *profiles); + + STACK_OF(SRTP_PROTECTION_PROFILE) *SSL_get_srtp_profiles(SSL *ssl); + SRTP_PROTECTION_PROFILE *SSL_get_selected_srtp_profile(SSL *s); + +=head1 DESCRIPTION + +SRTP is the Secure Real-Time Transport Protocol. OpenSSL implements support for +the "use_srtp" DTLS extension defined in RFC5764. This provides a mechanism for +establishing SRTP keying material, algorithms and parameters using DTLS. This +capability may be used as part of an implementation that conforms to RFC5763. +OpenSSL does not implement SRTP itself or RFC5763. Note that OpenSSL does not +support the use of SRTP Master Key Identifiers (MKIs). Also note that this +extension is only supported in DTLS. Any SRTP configuration will be ignored if a +TLS connection is attempted. + +An OpenSSL client wishing to send the "use_srtp" extension should call +SSL_CTX_set_tlsext_use_srtp() to set its use for all SSL objects subsequently +created from an SSL_CTX. Alternatively a client may call +SSL_set_tlsext_use_srtp() to set its use for an individual SSL object. The +B<profiles> parameters should point to a NUL-terminated, colon delimited list of +SRTP protection profile names. + +The currently supported protection profile names are: + +=over 4 + +=item SRTP_AES128_CM_SHA1_80 + +This corresponds to SRTP_AES128_CM_HMAC_SHA1_80 defined in RFC5764. + +=item SRTP_AES128_CM_SHA1_32 + +This corresponds to SRTP_AES128_CM_HMAC_SHA1_32 defined in RFC5764. + +=item SRTP_AEAD_AES_128_GCM + +This corresponds to the profile of the same name defined in RFC7714. + +=item SRTP_AEAD_AES_256_GCM + +This corresponds to the profile of the same name defined in RFC7714. + +=back + +Supplying an unrecognised protection profile name will result in an error. + +An OpenSSL server wishing to support the "use_srtp" extension should also call +SSL_CTX_set_tlsext_use_srtp() or SSL_set_tlsext_use_srtp() to indicate the +protection profiles that it is willing to negotiate. + +The currently configured list of protection profiles for either a client or a +server can be obtained by calling SSL_get_srtp_profiles(). This returns a stack +of SRTP_PROTECTION_PROFILE objects. The memory pointed to in the return value of +this function should not be freed by the caller. + +After a handshake has been completed the negotiated SRTP protection profile (if +any) can be obtained (on the client or the server) by calling +SSL_get_selected_srtp_profile(). This function will return NULL if no SRTP +protection profile was negotiated. The memory returned from this function should +not be freed by the caller. + +If an SRTP protection profile has been sucessfully negotiated then the SRTP +keying material (on both the client and server) should be obtained via a call to +L<SSL_export_keying_material(3)>. This call should provide a label value of +"EXTRACTOR-dtls_srtp" and a NULL context value (use_context is 0). The total +length of keying material obtained should be equal to two times the sum of the +master key length and the salt length as defined for the protection profile in +use. This provides the client write master key, the server write master key, the +client write master salt and the server write master salt in that order. + +=head1 RETURN VALUES + +SSL_CTX_set_tlsext_use_srtp() and SSL_set_tlsext_use_srtp() return 0 on success +or 1 on error. + +SSL_get_srtp_profiles() returns a stack of SRTP_PROTECTION_PROFILE objects on +success or NULL on error or if no protection profiles have been configured. + +SSL_get_selected_srtp_profile() returns a pointer to an SRTP_PROTECTION_PROFILE +object if one has been negotiated or NULL otherwise. + +=head1 SEE ALSO + +L<SSL_export_keying_material(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/UI_STRING.pod b/openssl-1.1.0h/doc/crypto/UI_STRING.pod new file mode 100644 index 0000000..340d9b2 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/UI_STRING.pod @@ -0,0 +1,135 @@ +=pod + +=head1 NAME + +UI_STRING, UI_string_types, UI_get_string_type, +UI_get_input_flags, UI_get0_output_string, +UI_get0_action_string, UI_get0_result_string, +UI_get0_test_string, UI_get_result_minsize, +UI_get_result_maxsize, UI_set_result +- User interface string parsing + +=head1 SYNOPSIS + + #include <openssl/ui.h> + + typedef struct ui_string_st UI_STRING; + + enum UI_string_types { + UIT_NONE = 0, + UIT_PROMPT, /* Prompt for a string */ + UIT_VERIFY, /* Prompt for a string and verify */ + UIT_BOOLEAN, /* Prompt for a yes/no response */ + UIT_INFO, /* Send info to the user */ + UIT_ERROR /* Send an error message to the user */ + }; + + enum UI_string_types UI_get_string_type(UI_STRING *uis); + int UI_get_input_flags(UI_STRING *uis); + const char *UI_get0_output_string(UI_STRING *uis); + const char *UI_get0_action_string(UI_STRING *uis); + const char *UI_get0_result_string(UI_STRING *uis); + const char *UI_get0_test_string(UI_STRING *uis); + int UI_get_result_minsize(UI_STRING *uis); + int UI_get_result_maxsize(UI_STRING *uis); + int UI_set_result(UI *ui, UI_STRING *uis, const char *result); + +=head1 DESCRIPTION + +The B<UI_STRING> gets created internally and added to a B<UI> whenever +one of the functions UI_add_input_string(), UI_dup_input_string(), +UI_add_verify_string(), UI_dup_verify_string(), +UI_add_input_boolean(), UI_dup_input_boolean(), UI_add_info_string(), +UI_dup_info_string(), UI_add_error_string() or UI_dup_error_string() +is called. +For a B<UI_METHOD> user, there's no need to know more. +For a B<UI_METHOD> creator, it is of interest to fetch text from these +B<UI_STRING> objects as well as adding results to some of them. + +UI_get_string_type() is used to retrieve the type of the given +B<UI_STRING>. + +UI_get_input_flags() is used to retrieve the flags associated with the +given B<UI_STRING>. + +UI_get0_output_string() is used to retrieve the actual string to +output (prompt, info, error, ...). + +UI_get0_action_string() is used to retrieve the action description +associated with a B<UIT_BOOLEAN> type B<UI_STRING>. +For all other B<UI_STRING> types, NULL is returned. +See L<UI_add_input_boolean(3)>. + +UI_get0_result_string() is used to retrieve the result of a prompt. +This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings. +For all other B<UI_STRING> types, NULL is returned. + +UI_get0_test_string() is used to retrieve the string to compare the +prompt result with. +This is only useful for B<UIT_VERIFY> type strings. +For all other B<UI_STRING> types, NULL is returned. + +UI_get_result_minsize() and UI_get_result_maxsize() are used to +retrieve the minimum and maximum required size of the result. +This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings. +For all other B<UI_STRING> types, -1 is returned. + +UI_set_result() is used to set the result value of a prompt. +For B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, this sets the +result retrievable with UI_get0_result_string() by copying the +contents of B<result> if its length fits the minimum and maximum size +requirements. +For B<UIT_BOOLEAN> type UI strings, this sets the first character of +the result retrievable with UI_get0_result_string() to the first +B<ok_char> given with UI_add_input_boolean() or UI_dup_input_boolean() +if the B<result> matched any of them, or the first of the +B<cancel_chars> if the B<result> matched any of them, otherwise it's +set to the NUL char C<\0>. +See L<UI_add_input_boolean(3)> for more information on B<ok_chars> and +B<cancel_chars>. + +=head1 RETURN VALUES + +UI_get_string_type() returns the UI string type. + +UI_get_input_flags() returns the UI string flags. + +UI_get0_output_string() returns the UI string output string. + +UI_get0_action_string() returns the UI string action description +string for B<UIT_BOOLEAN> type UI strings, NULL for any other type. + +UI_get0_result_string() returns the UI string result buffer for +B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, NULL for any other +type. + +UI_get0_test_string() returns the UI string action description +string for B<UIT_VERIFY> type UI strings, NULL for any other type. + +UI_get_result_minsize() returns the minimum allowed result size for +the UI string for for B<UIT_PROMPT> and B<UIT_VERIFY> type strings, +-1 for any other type. + +UI_get_result_maxsize() returns the minimum allowed result size for +the UI string for for B<UIT_PROMPT> and B<UIT_VERIFY> type strings, +-1 for any other type. + +UI_set_result() returns 0 on success or when the UI string is of any +type other than B<UIT_PROMPT>, B<UIT_VERIFY> or B<UIT_BOOLEAN>, -1 on +error. + +=head1 SEE ALSO + +L<UI(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut + diff --git a/openssl-1.1.0h/doc/crypto/UI_create_method.pod b/openssl-1.1.0h/doc/crypto/UI_create_method.pod new file mode 100644 index 0000000..1c40153 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/UI_create_method.pod @@ -0,0 +1,202 @@ +=pod + +=head1 NAME + +UI_METHOD, +UI_create_method, UI_destroy_method, UI_method_set_opener, +UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader, +UI_method_set_closer, UI_method_set_prompt_constructor, +UI_method_set_ex_data, UI_method_get_opener, UI_method_get_writer, +UI_method_get_flusher, UI_method_get_reader, UI_method_get_closer, +UI_method_get_prompt_constructor, UI_method_get_ex_data - user +interface method creation and destruction + +=head1 SYNOPSIS + + #include <openssl/ui.h> + + typedef struct ui_method_st UI_METHOD; + + UI_METHOD *UI_create_method(const char *name); + void UI_destroy_method(UI_METHOD *ui_method); + int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui)); + int UI_method_set_writer(UI_METHOD *method, + int (*writer) (UI *ui, UI_STRING *uis)); + int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui)); + int UI_method_set_reader(UI_METHOD *method, + int (*reader) (UI *ui, UI_STRING *uis)); + int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui)); + int UI_method_set_prompt_constructor(UI_METHOD *method, + char *(*prompt_constructor) (UI *ui, + const char + *object_desc, + const char + *object_name)); + int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data); + int (*UI_method_get_opener(const UI_METHOD *method)) (UI *); + int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *); + int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *); + int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *); + int (*UI_method_get_closer(const UI_METHOD *method)) (UI *); + char *(*UI_method_get_prompt_constructor(const UI_METHOD *method)) + (UI *, const char *, const char *); + const void *UI_method_get_ex_data(const UI_METHOD *method, int idx); + +=head1 DESCRIPTION + +A method contains a few functions that implement the low level of the +User Interface. +These functions are: + +=over 4 + +=item an opener + +This function takes a reference to a UI and starts a session, for +example by opening a channel to a tty, or by creating a dialog box. + +=item a writer + +This function takes a reference to a UI and a UI String, and writes +the string where appropriate, maybe to the tty, maybe added as a field +label in a dialog box. +Note that this gets fed all strings associated with a UI, one after +the other, so care must be taken which ones it actually uses. + +=item a flusher + +This function takes a reference to a UI, and flushes everything that +has been output so far. +For example, if the method builds up a dialog box, this can be used to +actually display it and accepting input ended with a pressed button. + +=item a reader + +This function takes a reference to a UI and a UI string and reads off +the given prompt, maybe from the tty, maybe from a field in a dialog +box. +Note that this gets fed all strings associated with a UI, one after +the other, so care must be taken which ones it actually uses. + +=item a closer + +This function takes a reference to a UI, and closes the session, maybe +by closing the channel to the tty, maybe by destroying a dialog box. + +=back + +All of these functions are expected to return 0 on error, 1 on +success, or -1 on out-off-band events, for example if some prompting +has been cancelled (by pressing Ctrl-C, for example). +Only the flusher or the reader are expected to return -1. +If returned by another of the functions, it's treated as if 0 was +returned. + +Regarding the writer and the reader, don't assume the former should +only write and don't assume the latter should only read. +This depends on the needs of the method. + +For example, a typical tty reader wouldn't write the prompts in the +write, but would rather do so in the reader, because of the sequential +nature of prompting on a tty. +This is how the UI_OpenSSL() method does it. + +In contrast, a method that builds up a dialog box would add all prompt +text in the writer, have all input read in the flusher and store the +results in some temporary buffer, and finally have the reader just +fetch those results. + +The central function that uses these method functions is UI_process(), +and it does it in five steps: + +=over 4 + +=item 1. + +Open the session using the opener function if that one's defined. +If an error occurs, jump to 5. + +=item 2. + +For every UI String associated with the UI, call the writer function +if that one's defined. +If an error occurs, jump to 5. + +=item 3. + +Flush everything using the flusher function if that one's defined. +If an error occurs, jump to 5. + +=item 4. + +For every UI String associated with the UI, call the reader function +if that one's defined. +If an error occurs, jump to 5. + +=item 5. + +Close the session using the closer function if that one's defined. + +=back + +UI_create_method() creates a new UI method with a given B<name>. + +UI_destroy_method() destroys the given UI method B<ui_method>. + +UI_method_set_opener(), UI_method_set_writer(), +UI_method_set_flusher(), UI_method_set_reader() and +UI_method_set_closer() set the five main method function to the given +function pointer. + +UI_method_set_prompt_constructor() sets the prompt constructor. +See L<UI_construct_prompt(3)>. + +UI_method_set_ex_data() sets application specific data with a given +EX_DATA index. +See L<CRYPTO_get_ex_new_index(3)> for general information on how to +get that index. + +UI_method_get_opener(), UI_method_get_writer(), +UI_method_get_flusher(), UI_method_get_reader(), +UI_method_get_closer() and UI_method_get_prompt_constructor() return +the different method functions. + +UI_method_get_ex_data() returns the application data previously stored +with UI_method_set_ex_data(). + +=head1 RETURN VALUES + +UI_create_method() returns a UI_METHOD pointer on success, NULL on +error. + +UI_method_set_opener(), UI_method_set_writer(), +UI_method_set_flusher(), UI_method_set_reader(), +UI_method_set_closer() and UI_method_set_prompt_constructor() return +0 on success, -1 if the given B<method> is NULL. + +UI_method_set_ex_data() returns 1 on success and 0 on error (because +CRYPTO_set_ex_data() does so). + +UI_method_get_opener(), UI_method_get_writer(), +UI_method_get_flusher(), UI_method_get_reader(), +UI_method_get_closer() and UI_method_get_prompt_constructor() return +the requested function pointer if it's set in the method, otherwise +NULL. + +UI_method_get_ex_data() returns a pointer to the application specific +data associated with the method. + +=head1 SEE ALSO + +L<UI(3)>, L<CRYPTO_get_ex_data(3)>, L<UI_STRING(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/UI_new.pod b/openssl-1.1.0h/doc/crypto/UI_new.pod new file mode 100644 index 0000000..5b98cf8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/UI_new.pod @@ -0,0 +1,203 @@ +=pod + +=head1 NAME + +UI, +UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, +UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, +UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, +UI_add_error_string, UI_dup_error_string, UI_construct_prompt, +UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, +UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, +UI_set_method, UI_OpenSSL, UI_null - user interface + +=head1 SYNOPSIS + + #include <openssl/ui.h> + + typedef struct ui_st UI; + + UI *UI_new(void); + UI *UI_new_method(const UI_METHOD *method); + void UI_free(UI *ui); + + int UI_add_input_string(UI *ui, const char *prompt, int flags, + char *result_buf, int minsize, int maxsize); + int UI_dup_input_string(UI *ui, const char *prompt, int flags, + char *result_buf, int minsize, int maxsize); + int UI_add_verify_string(UI *ui, const char *prompt, int flags, + char *result_buf, int minsize, int maxsize, const char *test_buf); + int UI_dup_verify_string(UI *ui, const char *prompt, int flags, + char *result_buf, int minsize, int maxsize, const char *test_buf); + int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, + const char *ok_chars, const char *cancel_chars, + int flags, char *result_buf); + int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, + const char *ok_chars, const char *cancel_chars, + int flags, char *result_buf); + int UI_add_info_string(UI *ui, const char *text); + int UI_dup_info_string(UI *ui, const char *text); + int UI_add_error_string(UI *ui, const char *text); + int UI_dup_error_string(UI *ui, const char *text); + + char *UI_construct_prompt(UI *ui_method, + const char *object_desc, const char *object_name); + + void *UI_add_user_data(UI *ui, void *user_data); + void *UI_get0_user_data(UI *ui); + + const char *UI_get0_result(UI *ui, int i); + + int UI_process(UI *ui); + + int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); + + void UI_set_default_method(const UI_METHOD *meth); + const UI_METHOD *UI_get_default_method(void); + const UI_METHOD *UI_get_method(UI *ui); + const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); + + UI_METHOD *UI_OpenSSL(void); + const UI_METHOD *UI_null(void); + +=head1 DESCRIPTION + +UI stands for User Interface, and is general purpose set of routines to +prompt the user for text-based information. Through user-written methods +(see L<UI_create_method(3)>), prompting can be done in any way +imaginable, be it plain text prompting, through dialog boxes or from a +cell phone. + +All the functions work through a context of the type UI. This context +contains all the information needed to prompt correctly as well as a +reference to a UI_METHOD, which is an ordered vector of functions that +carry out the actual prompting. + +The first thing to do is to create a UI with UI_new() or UI_new_method(), +then add information to it with the UI_add or UI_dup functions. Also, +user-defined random data can be passed down to the underlying method +through calls to UI_add_user_data. The default UI method doesn't care +about these data, but other methods might. Finally, use UI_process() +to actually perform the prompting and UI_get0_result() to find the result +to the prompt. + +A UI can contain more than one prompt, which are performed in the given +sequence. Each prompt gets an index number which is returned by the +UI_add and UI_dup functions, and has to be used to get the corresponding +result with UI_get0_result(). + +The functions are as follows: + +UI_new() creates a new UI using the default UI method. When done with +this UI, it should be freed using UI_free(). + +UI_new_method() creates a new UI using the given UI method. When done with +this UI, it should be freed using UI_free(). + +UI_OpenSSL() returns the built-in UI method (note: not necessarely the +default one, since the default can be changed. See further on). This +method is the most machine/OS dependent part of OpenSSL and normally +generates the most problems when porting. + +UI_null() returns a UI method that does nothing. Its use is to avoid +getting internal defaults for passed UI_METHOD pointers. + +UI_free() removes a UI from memory, along with all other pieces of memory +that's connected to it, like duplicated input strings, results and others. +If B<ui> is NULL nothing is done. + +UI_add_input_string() and UI_add_verify_string() add a prompt to the UI, +as well as flags and a result buffer and the desired minimum and maximum +sizes of the result, not counting the final NUL character. The given +information is used to prompt for information, for example a password, +and to verify a password (i.e. having the user enter it twice and check +that the same string was entered twice). UI_add_verify_string() takes +and extra argument that should be a pointer to the result buffer of the +input string that it's supposed to verify, or 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 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). + +UI_add_info_string() and UI_add_error_string() add strings that are shown at +the same time as the prompt for extra information or to show an error string. +The difference between the two is only conceptual. With the builtin method, +there's no technical difference between them. Other methods may make a +difference between them, however. + +The flags currently supported are B<UI_INPUT_FLAG_ECHO>, which is relevant for +UI_add_input_string() and will have the users response be echoed (when +prompting for a password, this flag should obviously not be used, and +B<UI_INPUT_FLAG_DEFAULT_PWD>, which means that a default password of some +sort will be used (completely depending on the application and the UI +method). + +UI_dup_input_string(), UI_dup_verify_string(), UI_dup_input_boolean(), +UI_dup_info_string() and UI_dup_error_string() are basically the same +as their UI_add counterparts, except that they make their own copies +of all strings. + +UI_construct_prompt() is a helper function that can be used to create +a prompt from two pieces of information: an description and a name. +The default constructor (if there is none provided by the method used) +creates a string "Enter I<description> for I<name>:". With the +description "pass phrase" and the file name "foo.key", that becomes +"Enter pass phrase for foo.key:". Other methods may create whatever +string and may include encodings that will be processed by the other +method functions. + +UI_add_user_data() adds a piece of memory for the method to use at any +time. The builtin UI method doesn't care about this info. Note that several +calls to this function doesn't add data, it replaces the previous blob +with the one given as argument. + +UI_get0_user_data() retrieves the data that has last been given to the +UI with UI_add_user_data(). + +UI_get0_result() returns a pointer to the result buffer associated with +the information indexed by I<i>. + +UI_process() goes through the information given so far, does all the printing +and prompting and returns the final status, which is -2 on out-of-band events +(Interrupt, Cancel, ...), -1 on error and 0 on success. + +UI_ctrl() adds extra control for the application author. For now, it +understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process() +print the OpenSSL error stack as part of processing the UI, and +B<UI_CTRL_IS_REDOABLE>, which returns a flag saying if the used UI can +be used again or not. + +UI_set_default_method() changes the default UI method to the one given. +This function is not thread-safe and should not be called at the same time +as other OpenSSL functions. + +UI_get_default_method() returns a pointer to the current default UI method. + +UI_get_method() returns the UI method associated with a given UI. + +UI_set_method() changes the UI method associated with a given UI. + +=head1 NOTES + +The resulting strings that the built in method UI_OpenSSL() generate +are assumed to be encoded according to the current locale or (for +Windows) code page. +For applications having different demands, these strings need to be +converted appropriately by the caller. +For Windows, if the OPENSSL_WIN32_UTF8 environment variable is set, +the built-in method UI_OpenSSL() will produce UTF-8 encoded strings +instead. + +=head1 COPYRIGHT + +Copyright 2001-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509V3_get_d2i.pod b/openssl-1.1.0h/doc/crypto/X509V3_get_d2i.pod new file mode 100644 index 0000000..ac560b2 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509V3_get_d2i.pod @@ -0,0 +1,241 @@ +=pod + +=head1 NAME + +X509_get0_extensions, X509_CRL_get0_extensions, X509_REVOKED_get0_extensions, +X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d, +X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i, +X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i, +X509_REVOKED_add1_ext_i2d - X509 extension decode and encode functions + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit, + int *idx); + int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value, + int crit, unsigned long flags); + + void *X509V3_EXT_d2i(X509_EXTENSION *ext); + X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext); + + void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx); + int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit, + unsigned long flags); + + void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx); + int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit, + unsigned long flags); + + void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx); + int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit, + unsigned long flags); + + const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x); + const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl); + const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r); + +=head1 DESCRIPTION + +X509V3_get_ext_d2i() looks for an extension with OID B<nid> in the extensions +B<x> and, if found, decodes it. If B<idx> is B<NULL> then only one +occurrence of an extension is permissible otherwise the first extension after +index B<*idx> is returned and B<*idx> updated to the location of the extension. +If B<crit> is not B<NULL> then B<*crit> is set to a status value: -2 if the +extension occurs multiple times (this is only returned if B<idx> is B<NULL>), +-1 if the extension could not be found, 0 if the extension is found and is +not critical and 1 if critical. A pointer to an extension specific structure +or B<NULL> is returned. + +X509V3_add1_i2d() adds extension B<value> to STACK B<*x> (allocating a new +STACK if necessary) using OID B<nid> and criticality B<crit> according +to B<flags>. + +X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension +B<ext> and returns a pointer to an extension specific structure or B<NULL> +if the extension could not be decoded (invalid syntax or not supported). + +X509V3_EXT_i2d() encodes the extension specific structure B<ext> +with OID B<ext_nid> and criticality B<crit>. + +X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of +certificate B<x>, they are otherwise identical to X509V3_get_d2i() and +X509V3_add_i2d(). + +X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions +of CRL B<crl>, they are otherwise identical to X509V3_get_d2i() and +X509V3_add_i2d(). + +X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the +extensions of B<X509_REVOKED> structure B<r> (i.e for CRL entry extensions), +they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d(). + +X509_get0_extensions(), X509_CRL_get0_extensions() and +X509_REVOKED_get0_extensions() return a stack of all the extensions +of a certificate a CRL or a CRL entry respectively. + +=head1 NOTES + +In almost all cases an extension can occur at most once and multiple +occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>. + +The B<flags> parameter may be one of the following values. + +B<X509V3_ADD_DEFAULT> appends a new extension only if the extension does +not already exist. An error is returned if the extension does already +exist. + +B<X509V3_ADD_APPEND> appends a new extension, ignoring whether the extension +already exists. + +B<X509V3_ADD_REPLACE> replaces an extension if it exists otherwise appends +a new extension. + +B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension if it exists +otherwise returns an error. + +B<X509V3_ADD_KEEP_EXISTING> appends a new extension only if the extension does +not already exist. An error B<is not> returned if the extension does already +exist. + +B<X509V3_ADD_DELETE> extension B<nid> is deleted: no new extension is added. + +If B<X509V3_ADD_SILENT> is ored with B<flags>: any error returned will not +be added to the error queue. + +The function X509V3_get_d2i() will return B<NULL> if the extension is not +found, occurs multiple times or cannot be decoded. It is possible to +determine the precise reason by checking the value of B<*crit>. + +=head1 SUPPORTED EXTENSIONS + +The following sections contain a list of all supported extensions +including their name and NID. + +=head2 PKIX Certificate Extensions + +The following certificate extensions are defined in PKIX standards such as +RFC5280. + + Basic Constraints NID_basic_constraints + Key Usage NID_key_usage + Extended Key Usage NID_ext_key_usage + + Subject Key Identifier NID_subject_key_identifier + Authority Key Identifier NID_authority_key_identifier + + Private Key Usage Period NID_private_key_usage_period + + Subject Alternative Name NID_subject_alt_name + Issuer Alternative Name NID_issuer_alt_name + + Authority Information Access NID_info_access + Subject Information Access NID_sinfo_access + + Name Constraints NID_name_constraints + + Certificate Policies NID_certificate_policies + Policy Mappings NID_policy_mappings + Policy Constraints NID_policy_constraints + Inhibit Any Policy NID_inhibit_any_policy + + TLS Feature NID_tlsfeature + +=head2 Netscape Certificate Extensions + +The following are (largely obsolete) Netscape certificate extensions. + + Netscape Cert Type NID_netscape_cert_type + Netscape Base Url NID_netscape_base_url + Netscape Revocation Url NID_netscape_revocation_url + Netscape CA Revocation Url NID_netscape_ca_revocation_url + Netscape Renewal Url NID_netscape_renewal_url + Netscape CA Policy Url NID_netscape_ca_policy_url + Netscape SSL Server Name NID_netscape_ssl_server_name + Netscape Comment NID_netscape_comment + +=head2 Miscellaneous Certificate Extensions + + Strong Extranet ID NID_sxnet + Proxy Certificate Information NID_proxyCertInfo + +=head2 PKIX CRL Extensions + +The following are CRL extensions from PKIX standards such as RFC5280. + + CRL Number NID_crl_number + CRL Distribution Points NID_crl_distribution_points + Delta CRL Indicator NID_delta_crl + Freshest CRL NID_freshest_crl + Invalidity Date NID_invalidity_date + Issuing Distribution Point NID_issuing_distribution_point + +The following are CRL entry extensions from PKIX standards such as RFC5280. + + CRL Reason Code NID_crl_reason + Certificate Issuer NID_certificate_issuer + +=head2 OCSP Extensions + + OCSP Nonce NID_id_pkix_OCSP_Nonce + OCSP CRL ID NID_id_pkix_OCSP_CrlID + Acceptable OCSP Responses NID_id_pkix_OCSP_acceptableResponses + OCSP No Check NID_id_pkix_OCSP_noCheck + OCSP Archive Cutoff NID_id_pkix_OCSP_archiveCutoff + OCSP Service Locator NID_id_pkix_OCSP_serviceLocator + Hold Instruction Code NID_hold_instruction_code + +=head2 Certificate Transparency Extensions + +The following extensions are used by certificate transparency, RFC6962 + + CT Precertificate SCTs NID_ct_precert_scts + CT Certificate SCTs NID_ct_cert_scts + +=head1 RETURN VALUES + +X509V3_EXT_d2i() and *X509V3_get_d2i() return a pointer to an extension +specific structure of B<NULL> if an error occurs. + +X509V3_EXT_i2d() returns a pointer to an B<X509_EXTENSION> structure +or B<NULL> if an error occurs. + +X509V3_add1_i2d() returns 1 if the operation is successful and 0 if it +fails due to a non-fatal error (extension not found, already exists, +cannot be encoded) or -1 due to a fatal error such as a memory allocation +failure. + +X509_get0_extensions(), X509_CRL_get0_extensions() and +X509_REVOKED_get0_extensions() return a stack of extensions. They return +NULL if no extensions are present. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_ALGOR_dup.pod b/openssl-1.1.0h/doc/crypto/X509_ALGOR_dup.pod new file mode 100644 index 0000000..21845e9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_ALGOR_dup.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +X509_ALGOR_dup, X509_ALGOR_set0, X509_ALGOR_get0, X509_ALGOR_set_md, X509_ALGOR_cmp - AlgorithmIdentifier functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509_ALGOR *X509_ALGOR_dup(X509_ALGOR *alg); + int X509_ALGOR_set0(X509_ALGOR *alg, ASN1_OBJECT *aobj, int ptype, void *pval); + void X509_ALGOR_get0(const ASN1_OBJECT **paobj, int *pptype, + const void **ppval, const X509_ALGOR *alg); + void X509_ALGOR_set_md(X509_ALGOR *alg, const EVP_MD *md); + int X509_ALGOR_cmp(const X509_ALGOR *a, const X509_ALGOR *b); + +=head1 DESCRIPTION + +X509_ALGOR_dup() returns a copy of B<alg>. + +X509_ALGOR_set0() sets the algorithm OID of B<alg> to B<aobj> and the +associated parameter type to B<ptype> with value B<pval>. If B<ptype> is +B<V_ASN1_UNDEF> the parameter is omitted, otherwise B<ptype> and B<pval> have +the same meaning as the B<type> and B<value> parameters to ASN1_TYPE_set(). +All the supplied parameters are used internally so must B<NOT> be freed after +this call. + +X509_ALGOR_get0() is the inverse of X509_ALGOR_set0(): it returns the +algorithm OID in B<*paobj> and the associated parameter in B<*pptype> +and B<*ppval> from the B<AlgorithmIdentifier> B<alg>. + +X509_ALGOR_set_md() sets the B<AlgorithmIdentifier> B<alg> to appropriate +values for the message digest B<md>. + +X509_ALGOR_cmp() compares B<a> and B<b> and returns 0 if they have identical +encodings and non-zero otherwise. + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_CRL_get0_by_serial.pod b/openssl-1.1.0h/doc/crypto/X509_CRL_get0_by_serial.pod new file mode 100644 index 0000000..a704228 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_CRL_get0_by_serial.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +X509_CRL_get0_by_serial, X509_CRL_get0_by_cert, X509_CRL_get_REVOKED, +X509_REVOKED_get0_serialNumber, X509_REVOKED_get0_revocationDate, +X509_REVOKED_set_serialNumber, X509_REVOKED_set_revocationDate, +X509_CRL_add0_revoked, X509_CRL_sort - CRL revoked entry utility +functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_CRL_get0_by_serial(X509_CRL *crl, + X509_REVOKED **ret, ASN1_INTEGER *serial); + int X509_CRL_get0_by_cert(X509_CRL *crl, X509_REVOKED **ret, X509 *x); + + STACK_OF(X509_REVOKED) *X509_CRL_get_REVOKED(X509_CRL *crl); + + const ASN1_INTEGER *X509_REVOKED_get0_serialNumber(const X509_REVOKED *r); + const ASN1_TIME *X509_REVOKED_get0_revocationDate(const X509_REVOKED *r); + + int X509_REVOKED_set_serialNumber(X509_REVOKED *r, ASN1_INTEGER *serial); + int X509_REVOKED_set_revocationDate(X509_REVOKED *r, ASN1_TIME *tm); + + int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); + + int X509_CRL_sort(X509_CRL *crl); + +=head1 DESCRIPTION + +X509_CRL_get0_by_serial() attempts to find a revoked entry in B<crl> for +serial number B<serial>. If it is successful it sets B<*ret> to the internal +pointer of the matching entry, as a result B<*ret> must not be freed up +after the call. + +X509_CRL_get0_by_cert() is similar to X509_get0_by_serial() except it +looks for a revoked entry using the serial number of certificate B<x>. + +X509_CRL_get_REVOKED() returns an internal pointer to a stack of all +revoked entries for B<crl>. + +X509_REVOKED_get0_serialNumber() returns an internal pointer to the +serial number of B<r>. + +X509_REVOKED_get0_revocationDate() returns an internal pointer to the +revocation date of B<r>. + +X509_REVOKED_set_serialNumber() sets the serial number of B<r> to B<serial>. +The supplied B<serial> pointer is not used internally so it should be +freed up after use. + +X509_REVOKED_set_revocationDate() sets the revocation date of B<r> to +B<tm>. The supplied B<tm> pointer is not used internally so it should be +freed up after use. + +X509_CRL_add0_revoked() appends revoked entry B<rev> to CRL B<crl>. The +pointer B<rev> is used internally so it must not be freed up after the call: +it is freed when the parent CRL is freed. + +X509_CRL_sort() sorts the revoked entries of B<crl> into ascending serial +number order. + +=head1 NOTES + +Applications can determine the number of revoked entries returned by +X509_CRL_get_revoked() using sk_X509_REVOKED_num() and examine each one +in turn using sk_X509_REVOKED_value(). + +=head1 RETURN VALUES + +X509_CRL_get0_by_serial() and X509_CRL_get0_by_cert() return 0 for failure, +1 on success except if the revoked entry has the reason C<removeFromCRL> (8), +in which case 2 is returned. + +X509_REVOKED_set_serialNumber(), X509_REVOKED_set_revocationDate(), +X509_CRL_add0_revoked() and X509_CRL_sort() return 1 for success and 0 for +failure. + +X509_REVOKED_get0_serialNumber() returns an B<ASN1_INTEGER> pointer. + +X509_REVOKED_get0_revocationDate() returns an B<ASN1_TIME> value. + +X509_CRL_get_REVOKED() returns a STACK of revoked entries. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_EXTENSION_set_object.pod b/openssl-1.1.0h/doc/crypto/X509_EXTENSION_set_object.pod new file mode 100644 index 0000000..f3f0de6 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_EXTENSION_set_object.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +X509_EXTENSION_set_object, X509_EXTENSION_set_critical, +X509_EXTENSION_set_data, X509_EXTENSION_create_by_NID, +X509_EXTENSION_create_by_OBJ, X509_EXTENSION_get_object, +X509_EXTENSION_get_critical, X509_EXTENSION_get_data - extension utility +functions + +=head1 SYNOPSIS + + int X509_EXTENSION_set_object(X509_EXTENSION *ex, const ASN1_OBJECT *obj); + int X509_EXTENSION_set_critical(X509_EXTENSION *ex, int crit); + int X509_EXTENSION_set_data(X509_EXTENSION *ex, ASN1_OCTET_STRING *data); + + X509_EXTENSION *X509_EXTENSION_create_by_NID(X509_EXTENSION **ex, + int nid, int crit, + ASN1_OCTET_STRING *data); + X509_EXTENSION *X509_EXTENSION_create_by_OBJ(X509_EXTENSION **ex, + const ASN1_OBJECT *obj, int crit, + ASN1_OCTET_STRING *data); + + ASN1_OBJECT *X509_EXTENSION_get_object(X509_EXTENSION *ex); + int X509_EXTENSION_get_critical(const X509_EXTENSION *ex); + ASN1_OCTET_STRING *X509_EXTENSION_get_data(X509_EXTENSION *ne); + +=head1 DESCRIPTION + +X509_EXTENSION_set_object() sets the extension type of B<ex> to B<obj>. The +B<obj> pointer is duplicated internally so B<obj> should be freed up after use. + +X509_EXTENSION_set_critical() sets the criticality of B<ex> to B<crit>. If +B<crit> is zero the extension in non-critical otherwise it is critical. + +X509_EXTENSION_set_data() sets the data in extension B<ex> to B<data>. The +B<data> pointer is duplicated internally. + +X509_EXTENSION_create_by_NID() creates an extension of type B<nid>, +criticality B<crit> using data B<data>. The created extension is returned and +written to B<*ex> reusing or allocating a new extension if necessary so B<*ex> +should either be B<NULL> or a valid B<X509_EXTENSION> structure it must +B<not> be an uninitialised pointer. + +X509_EXTENSION_create_by_OBJ() is identical to X509_EXTENSION_create_by_NID() +except it creates and extension using B<obj> instead of a NID. + +X509_EXTENSION_get_object() returns the extension type of B<ex> as an +B<ASN1_OBJECT> pointer. The returned pointer is an internal value which must +not be freed up. + +X509_EXTENSION_get_critical() returns the criticality of extension B<ex> it +returns B<1> for critical and B<0> for non-critical. + +X509_EXTENSION_get_data() returns the data of extension B<ex>. The returned +pointer is an internal value which must not be freed up. + +=head1 NOTES + +These functions manipulate the contents of an extension directly. Most +applications will want to parse or encode and add an extension: they should +use the extension encode and decode functions instead such as +X509_add1_ext_i2d() and X509_get_ext_d2i(). + +The B<data> associated with an extension is the extension encoding in an +B<ASN1_OCTET_STRING> structure. + +=head1 RETURN VALUES + +X509_EXTENSION_set_object() X509_EXTENSION_set_critical() and +X509_EXTENSION_set_data() return B<1> for success and B<0> for failure. + +X509_EXTENSION_create_by_NID() and X509_EXTENSION_create_by_OBJ() return +an B<X509_EXTENSION> pointer or B<NULL> if an error occurs. + +X509_EXTENSION_get_object() returns an B<ASN1_OBJECT> pointer. + +X509_EXTENSION_get_critical() returns B<0> for non-critical and B<1> for +critical. + +X509_EXTENSION_get_data() returns an B<ASN1_OCTET_STRING> pointer. + +=head1 SEE ALSO + +L<X509V3_get_d2i(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_LOOKUP_hash_dir.pod b/openssl-1.1.0h/doc/crypto/X509_LOOKUP_hash_dir.pod new file mode 100644 index 0000000..5f8dfa9 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_LOOKUP_hash_dir.pod @@ -0,0 +1,130 @@ +=pod + +=head1 NAME + +X509_LOOKUP_hash_dir, X509_LOOKUP_file, +X509_load_cert_file, +X509_load_crl_file, +X509_load_cert_crl_file - Default OpenSSL certificate +lookup methods + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); + X509_LOOKUP_METHOD *X509_LOOKUP_file(void); + + int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type); + int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); + int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type); + +=head1 DESCRIPTION + +B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate +lookup methods to use with B<X509_STORE>, provided by OpenSSL library. + +Users of the library typically do not need to create instances of these +methods manually, they would be created automatically by +L<X509_STORE_load_locations(3)> or +L<SSL_CTX_load_verify_locations(3)> +functions. + +Internally loading of certificates and CRLs is implemented via functions +B<X509_load_cert_crl_file>, B<X509_load_cert_file> and +B<X509_load_crl_file>. These functions support parameter I<type>, which +can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and +B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified +file into memory cache of B<X509_STORE> objects which given B<ctx> +parameter is associated with. + +Functions B<X509_load_cert_file> and +B<X509_load_crl_file> can load both PEM and DER formats depending of +type value. Because DER format cannot contain more than one certificate +or CRL object (while PEM can contain several concatenated PEM objects) +B<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to +B<X509_load_cert_file>. + +Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions +to load default certificate store file (see +L<X509_STORE_set_default_paths(3)>. + + +Functions return number of objects loaded from file or 0 in case of +error. + +Both methods support adding several certificate locations into one +B<X509_STORE>. + +This page documents certificate store formats used by these methods and +caching policy. + +=head2 File Method + +The B<X509_LOOKUP_file> method loads all the certificates or CRLs +present in a file into memory at the time the file is added as a +lookup source. + +File format is ASCII text which contains concatenated PEM certificates +and CRLs. + +This method should be used by applications which work with a small +set of CAs. + +=head2 Hashed Directory Method + +B<X509_LOOKUP_hash_dir> is a more advanced method, which loads +certificates and CRLs on demand, and caches them in memory once +they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs +upon each lookup, so that newer CRLs are as soon as they appear in +the directory. + +The directory should contain one certificate or CRL per file in PEM format, +with a file name of the form I<hash>.I<N> for a certificate, or +I<hash>.B<r>I<N> for a CRL. +The I<hash> is the value returned by the L<X509_NAME_hash(3)> function applied +to the subject name for certificates or issuer name for CRLs. +The hash can also be obtained via the B<-hash> option of the L<x509(1)> or +L<crl(1)> commands. + +The .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is +incremented consecutively for each certificate or CRL with the same I<hash> +value. +Gaps in the sequence numbers are not supported, it is assumed that there are no +more objects with the same hash beyond the first missing number in the +sequence. + +Sequence numbers make it possible for the directory to contain multiple +certificates with same subject name hash value. +For example, it is possible to have in the store several certificates with same +subject or several CRLs with same issuer (and, for example, different validity +period). + +When checking for new CRLs once one CRL for given hash value is +loaded, hash_dir lookup method checks only for certificates with +sequence number greater than that of the already cached CRL. + +Note that the hash algorithm used for subject name hashing changed in OpenSSL +1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL +0.9.8 to 1.0.0. + +OpenSSL includes a L<rehash(1)> utility which creates symlinks with correct +hashed names for all files with .pem suffix in a given directory. + +=head1 SEE ALSO + +L<PEM_read_PrivateKey(3)>, +L<X509_STORE_load_locations(3)>, +L<X509_store_add_lookup(3)>, +L<SSL_CTX_load_verify_locations(3)>, + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_NAME_ENTRY_get_object.pod b/openssl-1.1.0h/doc/crypto/X509_NAME_ENTRY_get_object.pod new file mode 100644 index 0000000..72e0f7b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_NAME_ENTRY_get_object.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data, +X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data, +X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID, +X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + ASN1_OBJECT * X509_NAME_ENTRY_get_object(const X509_NAME_ENTRY *ne); + ASN1_STRING * X509_NAME_ENTRY_get_data(const X509_NAME_ENTRY *ne); + + int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, const ASN1_OBJECT *obj); + int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len); + + X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len); + X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type, const unsigned char *bytes, int len); + X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len); + +=head1 DESCRIPTION + +X509_NAME_ENTRY_get_object() retrieves the field name of B<ne> in +and B<ASN1_OBJECT> structure. + +X509_NAME_ENTRY_get_data() retrieves the field value of B<ne> in +and B<ASN1_STRING> structure. + +X509_NAME_ENTRY_set_object() sets the field name of B<ne> to B<obj>. + +X509_NAME_ENTRY_set_data() sets the field value of B<ne> to string type +B<type> and value determined by B<bytes> and B<len>. + +X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID() +and X509_NAME_ENTRY_create_by_OBJ() create and return an +B<X509_NAME_ENTRY> structure. + +=head1 NOTES + +X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be +used to examine an B<X509_NAME_ENTRY> function as returned by +X509_NAME_get_entry() for example. + +X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(), +and X509_NAME_ENTRY_create_by_OBJ() create and return an + +X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(), +X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data() +are seldom used in practice because B<X509_NAME_ENTRY> structures +are almost always part of B<X509_NAME> structures and the +corresponding B<X509_NAME> functions are typically used to +create and add new entries in a single operation. + +The arguments of these functions support similar options to the similarly +named ones of the corresponding B<X509_NAME> functions such as +X509_NAME_add_entry_by_txt(). So for example B<type> can be set to +B<MBSTRING_ASC> but in the case of X509_set_data() the field name must be +set first so the relevant field information can be looked up internally. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>, +L<OBJ_nid2obj(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_NAME_add_entry_by_txt.pod b/openssl-1.1.0h/doc/crypto/X509_NAME_add_entry_by_txt.pod new file mode 100644 index 0000000..27e5baf --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_NAME_add_entry_by_txt.pod @@ -0,0 +1,123 @@ +=pod + +=head1 NAME + +X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID, +X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set); + + int X509_NAME_add_entry_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len, int loc, int set); + + int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, const unsigned char *bytes, int len, int loc, int set); + + int X509_NAME_add_entry(X509_NAME *name, const X509_NAME_ENTRY *ne, int loc, int set); + + X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc); + +=head1 DESCRIPTION + +X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and +X509_NAME_add_entry_by_NID() add a field whose name is defined +by a string B<field>, an object B<obj> or a NID B<nid> respectively. +The field value to be added is in B<bytes> of length B<len>. If +B<len> is -1 then the field length is calculated internally using +strlen(bytes). + +The type of field is determined by B<type> which can either be a +definition of the type of B<bytes> (such as B<MBSTRING_ASC>) or a +standard ASN1 type (such as B<V_ASN1_IA5STRING>). The new entry is +added to a position determined by B<loc> and B<set>. + +X509_NAME_add_entry() adds a copy of B<X509_NAME_ENTRY> structure B<ne> +to B<name>. The new entry is added to a position determined by B<loc> +and B<set>. Since a copy of B<ne> is added B<ne> must be freed up after +the call. + +X509_NAME_delete_entry() deletes an entry from B<name> at position +B<loc>. The deleted entry is returned and must be freed up. + +=head1 NOTES + +The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8> +is strongly recommended for the B<type> parameter. This allows the +internal code to correctly determine the type of the field and to +apply length checks according to the relevant standards. This is +done using ASN1_STRING_set_by_NID(). + +If instead an ASN1 type is used no checks are performed and the +supplied data in B<bytes> is used directly. + +In X509_NAME_add_entry_by_txt() the B<field> string represents +the field name using OBJ_txt2obj(field, 0). + +The B<loc> and B<set> parameters determine where a new entry should +be added. For almost all applications B<loc> can be set to -1 and B<set> +to 0. This adds a new entry to the end of B<name> as a single valued +RelativeDistinguishedName (RDN). + +B<loc> actually determines the index where the new entry is inserted: +if it is -1 it is appended. + +B<set> determines how the new type is added. If it is zero a +new RDN is created. + +If B<set> is -1 or 1 it is added to the previous or next RDN +structure respectively. This will then be a multivalued RDN: +since multivalues RDNs are very seldom used B<set> is almost +always set to zero. + +=head1 EXAMPLES + +Create an B<X509_NAME> structure: + +"C=UK, O=Disorganized Organization, CN=Joe Bloggs" + + X509_NAME *nm; + nm = X509_NAME_new(); + if (nm == NULL) + /* Some error */ + if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC, + "UK", -1, -1, 0)) + /* Error */ + 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, "CN", MBSTRING_ASC, + "Joe Bloggs", -1, -1, 0)) + /* Error */ + +=head1 RETURN VALUES + +X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(), +X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for +success of 0 if an error occurred. + +X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY> +structure of B<NULL> if an error occurred. + +=head1 BUGS + +B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a +different algorithm to determine field types. Since this form does +not understand multicharacter types, performs no length checks and +can result in invalid field types its use is strongly discouraged. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<d2i_X509_NAME(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_NAME_get0_der.pod b/openssl-1.1.0h/doc/crypto/X509_NAME_get0_der.pod new file mode 100644 index 0000000..f91fd4d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_NAME_get0_der.pod @@ -0,0 +1,40 @@ +=pod + +=head1 NAME + +X509_NAME_get0_der - get X509_NAME DER encoding + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_NAME_get0_der(X509_NAME *nm, const unsigned char **pder, + size_t *pderlen) + + +=head1 DESCRIPTION + +The function X509_NAME_get0_der() returns an internal pointer to the +encoding of an B<X509_NAME> structure in B<*pder> and consisting of +B<*pderlen> bytes. It is useful for applications that wish to examine +the encoding of an B<X509_NAME> structure without copying it. + +=head1 RETURN VALUES + +The function X509_NAME_get0_der() returns 1 for success and 0 if an error +occurred. + +=head1 SEE ALSO + +L<d2i_X509(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_NAME_get_index_by_NID.pod b/openssl-1.1.0h/doc/crypto/X509_NAME_get_index_by_NID.pod new file mode 100644 index 0000000..2d6713b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_NAME_get_index_by_NID.pod @@ -0,0 +1,123 @@ +=pod + +=head1 NAME + +X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, +X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ - +X509_NAME lookup and enumeration functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_NAME_get_index_by_NID(X509_NAME *name, int nid, int lastpos); + int X509_NAME_get_index_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int lastpos); + + int X509_NAME_entry_count(const X509_NAME *name); + X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc); + + int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf, int len); + int X509_NAME_get_text_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, char *buf, int len); + +=head1 DESCRIPTION + +These functions allow an B<X509_NAME> structure to be examined. The +B<X509_NAME> structure is the same as the B<Name> type defined in +RFC2459 (and elsewhere) and used for example in certificate subject +and issuer names. + +X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve +the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos> +should initially be set to -1. If there are no more entries -1 is returned. +If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned. + +X509_NAME_entry_count() returns the total number of entries in B<name>. + +X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name> +corresponding to index B<loc>. Acceptable values for B<loc> run from +0 to (X509_NAME_entry_count(name) - 1). The value returned is an +internal pointer which must not be freed. + +X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve +the "text" from the first entry in B<name> which matches B<nid> or +B<obj>, if no such entry exists -1 is returned. At most B<len> bytes +will be written and the text written to B<buf> will be null +terminated. The length of the output string written is returned +excluding the terminating null. If B<buf> is <NULL> then the amount +of space needed in B<buf> (excluding the final null) is returned. + +=head1 NOTES + +X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are +legacy functions which have various limitations which make them +of minimal use in practice. They can only find the first matching +entry and will copy the contents of the field verbatim: this can +be highly confusing if the target is a multicharacter string type +like a BMPString or a UTF8String. + +For a more general solution X509_NAME_get_index_by_NID() or +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>. + +Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID() +should check for the return value of -2. Alternatively the NID validity +can be determined first by checking OBJ_nid2obj(nid) is not NULL. + +=head1 EXAMPLES + +Process all entries: + + int i; + X509_NAME_ENTRY *e; + + for (i = 0; i < X509_NAME_entry_count(nm); i++) + { + e = X509_NAME_get_entry(nm, i); + /* Do something with e */ + } + +Process all commonName entries: + + int lastpos = -1; + X509_NAME_ENTRY *e; + + for (;;) + { + lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); + if (lastpos == -1) + break; + e = X509_NAME_get_entry(nm, lastpos); + /* Do something with e */ + } + +=head1 RETURN VALUES + +X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() +return the index of the next matching entry or -1 if not found. +X509_NAME_get_index_by_NID() can also return -2 if the supplied +NID is invalid. + +X509_NAME_entry_count() returns the total number of entries. + +X509_NAME_get_entry() returns an B<X509_NAME> pointer to the +requested entry or B<NULL> if the index is invalid. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<d2i_X509_NAME(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_NAME_print_ex.pod b/openssl-1.1.0h/doc/crypto/X509_NAME_print_ex.pod new file mode 100644 index 0000000..3e9caa8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_NAME_print_ex.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, +X509_NAME_oneline - X509_NAME printing routines + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_NAME_print_ex(BIO *out, const X509_NAME *nm, int indent, unsigned long flags); + int X509_NAME_print_ex_fp(FILE *fp, const X509_NAME *nm, int indent, unsigned long flags); + char * X509_NAME_oneline(const X509_NAME *a, char *buf, int size); + int X509_NAME_print(BIO *bp, const X509_NAME *name, int obase); + +=head1 DESCRIPTION + +X509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. Each +line (for multiline formats) is indented by B<indent> spaces. The output format +can be extensively customised by use of the B<flags> parameter. + +X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is +written to FILE pointer B<fp>. + +X509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. +If B<buf> is B<NULL> then a buffer is dynamically allocated and returned, and +B<size> is ignored. +Otherwise, at most B<size> bytes will be written, including the ending '\0', +and B<buf> is returned. + +X509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase> +characters. Multiple lines are used if the output (including indent) exceeds +80 characters. + +=head1 NOTES + +The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions which +produce a non standard output form, they don't handle multi character fields and +have various quirks and inconsistencies. Their use is strongly discouraged in new +applications. + +Although there are a large number of possible flags for most purposes +B<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice. +As noted on the L<ASN1_STRING_print_ex(3)> manual page +for UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example +B<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used. + +The complete set of the flags supported by X509_NAME_print_ex() is listed below. + +Several options can be ored together. + +The options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>, +B<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field separators +to use. Two distinct separators are used between distinct RelativeDistinguishedName +components and separate values in the same RDN for a multi-valued RDN. Multi-valued +RDNs are currently very rare so the second separator will hardly ever be used. + +B<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. B<XN_FLAG_SEP_CPLUS_SPC> +uses comma and plus with spaces: this is more readable that plain comma and plus. +B<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and plus. B<XN_FLAG_SEP_MULTILINE> uses +spaced newline and plus respectively. + +If B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order. + +The fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>, +B<XN_FLAG_FN_NONE> determine how a field name is displayed. It will +use the short name (e.g. CN) the long name (e.g. commonName) always +use OID numerical form (normally OIDs are only used if the field name is not +recognised) and no field name respectively. + +If B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character +separating field names and values. + +If B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is +printed instead of the values. + +If B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this +is only of use for multiline format. + +Additionally all the options supported by ASN1_STRING_print_ex() can be used to +control how each field value is displayed. + +In addition a number options can be set for commonly used formats. + +B<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it +is equivalent to: + B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS> + + +B<XN_FLAG_ONELINE> is a more readable one line format which is the same as: + B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN> + +B<XN_FLAG_MULTILINE> is a multiline format which is the same as: + B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN> + +B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally. + +=head1 SEE ALSO + +L<ASN1_STRING_print_ex(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_PUBKEY_new.pod b/openssl-1.1.0h/doc/crypto/X509_PUBKEY_new.pod new file mode 100644 index 0000000..b133105 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_PUBKEY_new.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + +X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0, +X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp, +i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, +X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509_PUBKEY *X509_PUBKEY_new(void); + void X509_PUBKEY_free(X509_PUBKEY *a); + + int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey); + EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key); + EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key); + + EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length); + int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp); + + EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a); + EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a); + + int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey); + int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey); + + int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj, + int ptype, void *pval, + unsigned char *penc, int penclen); + int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg, + const unsigned char **pk, int *ppklen, + X509_ALGOR **pa, X509_PUBKEY *pub); + +=head1 DESCRIPTION + +The B<X509_PUBKEY> structure represents the ASN.1 B<SubjectPublicKeyInfo> +structure defined in RFC5280 and used in certificates and certificate requests. + +X509_PUBKEY_new() allocates and initializes an B<X509_PUBKEY> structure. + +X509_PUBKEY_free() frees up B<X509_PUBKEY> structure B<a>. If B<a> is NULL +nothing is done. + +X509_PUBKEY_set() sets the public key in B<*x> to the public key contained +in the B<EVP_PKEY> structure B<pkey>. If B<*x> is not NULL any existing +public key structure will be freed. + +X509_PUBKEY_get0() returns the public key contained in B<key>. The returned +value is an internal pointer which B<MUST NOT> be freed after use. + +X509_PUBKEY_get() is similar to X509_PUBKEY_get0() except the reference +count on the returned key is incremented so it B<MUST> be freed using +EVP_PKEY_free() after use. + +d2i_PUBKEY() and i2d_PUBKEY() decode and encode an B<EVP_PKEY> structure +using B<SubjectPublicKeyInfo> format. They otherwise follow the conventions of +other ASN.1 functions such as d2i_X509(). + +d2i_PUBKEY_bio(), d2i_PUBKEY_fp(), i2d_PUBKEY_bio() and i2d_PUBKEY_fp() are +similar to d2i_PUBKEY() and i2d_PUBKEY() except they decode or encode using a +B<BIO> or B<FILE> pointer. + +X509_PUBKEY_set0_param() sets the public key parameters of B<pub>. The +OID associated with the algorithm is set to B<aobj>. The type of the +algorithm parameters is set to B<type> using the structure B<pval>. +The encoding of the public key itself is set to the B<penclen> +bytes contained in buffer B<penc>. On success ownership of all the supplied +parameters is passed to B<pub> so they must not be freed after the +call. + +X509_PUBKEY_get0_param() retrieves the public key parameters from B<pub>, +B<*ppkalg> is set to the associated OID and the encoding consists of +B<*ppklen> bytes at B<*pk>, B<*pa> is set to the associated +AlgorithmIdentifier for the public key. If the value of any of these +parameters is not required it can be set to B<NULL>. All of the +retrieved pointers are internal and must not be freed after the +call. + +=head1 NOTES + +The B<X509_PUBKEY> functions can be used to encode and decode public keys +in a standard format. + +In many cases applications will not call the B<X509_PUBKEY> functions +directly: they will instead call wrapper functions such as X509_get0_pubkey(). + +=head1 RETURN VALUES + +If the allocation fails, X509_PUBKEY_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)>. + +Otherwise it returns a pointer to the newly allocated structure. + +X509_PUBKEY_free() does not return a value. + +X509_PUBKEY_get0() and X509_PUBKEY_get() return a pointer to an B<EVP_PKEY> +structure or B<NULL> if an error occurs. + +X509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param() +return 1 for success and 0 if an error occurred. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_get_pubkey(3)>, + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_SIG_get0.pod b/openssl-1.1.0h/doc/crypto/X509_SIG_get0.pod new file mode 100644 index 0000000..d24eadc --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_SIG_get0.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +X509_SIG_get0, X509_SIG_getm - DigestInfo functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + void X509_SIG_get0(const X509_SIG *sig, const X509_ALGOR **palg, + const ASN1_OCTET_STRING **pdigest); + void X509_SIG_getm(X509_SIG *sig, X509_ALGOR **palg, + ASN1_OCTET_STRING **pdigest, + +=head1 DESCRIPTION + +X509_SIG_get0() returns pointers to the algorithm identifier and digest +value in B<sig>. X509_SIG_getm() is identical to X509_SIG_get0() +except the pointers returned are not constant and can be modified: +for example to initialise them. + +=head1 SEE ALSO + +L<d2i_X509(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_get_error.pod b/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_get_error.pod new file mode 100644 index 0000000..105e051 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_get_error.pod @@ -0,0 +1,338 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, +X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth, +X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert, +X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain, +X509_verify_cert_error_string - get or set certificate verification status +information + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int s); + int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_error_depth(X509_STORE_CTX *ctx, int depth); + X509 *X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_current_cert(X509_STORE_CTX *ctx, X509 *x); + X509 *X509_STORE_CTX_get0_cert(X509_STORE_CTX *ctx); + + STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); + + const char *X509_verify_cert_error_string(long n); + +=head1 DESCRIPTION + +These functions are typically called after X509_verify_cert() has indicated +an error or in a verification callback to determine the nature of an error. + +X509_STORE_CTX_get_error() returns the error code of B<ctx>, see +the B<ERROR CODES> section for a full description of all error codes. + +X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example +it might be used in a verification callback to set an error based on additional +checks. + +X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a +non-negative integer representing where in the certificate chain the error +occurred. If it is zero it occurred in the end entity certificate, one if +it is the certificate which signed the end entity certificate and so on. + +X509_STORE_CTX_set_error_depth() sets the error B<depth>. +This can be used in combination with X509_STORE_CTX_set_error() to set the +depth at which an error condition was detected. + +X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which +caused the error or B<NULL> if no certificate is relevant. + +X509_STORE_CTX_set_current_cert() sets the certificate B<x> in B<ctx> which +caused the error. +This value is not intended to remain valid for very long, and remains owned by +the caller. +It may be examined by a verification callback invoked to handle each error +encountered during chain verification and is no longer required after such a +callback. +If a callback wishes the save the certificate for use after it returns, it +needs to increment its reference count via L<X509_up_ref(3)>. +Once such a I<saved> certificate is no longer needed it can be freed with +L<X509_free(3)>. + +X509_STORE_CTX_get0_cert() retrieves an internal pointer to the +certificate being verified by the B<ctx>. + +X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous +call to X509_verify_cert() is successful. If the call to X509_verify_cert() +is B<not> successful the returned chain may be incomplete or invalid. The +returned chain persists after the B<ctx> structure is freed, when it is +no longer needed it should be free up using: + + sk_X509_pop_free(chain, X509_free); + +X509_verify_cert_error_string() returns a human readable error string for +verification error B<n>. + +=head1 RETURN VALUES + +X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code. + +X509_STORE_CTX_get_error_depth() returns a non-negative error depth. + +X509_STORE_CTX_get_current_cert() returns the certificate which caused the +error or B<NULL> if no certificate is relevant to the error. + +X509_verify_cert_error_string() returns a human readable error string for +verification error B<n>. + +=head1 ERROR CODES + +A list of error codes and messages is shown below. Some of the +error codes are defined but currently never returned: these are described as +"unused". + +=over 4 + +=item B<X509_V_OK: ok> + +the operation was successful. + +=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> + +the issuer certificate could not be found: this occurs if the issuer certificate +of an untrusted certificate cannot be found. + +=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> + +the CRL of a certificate could not be found. + +=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> + +the certificate signature could not be decrypted. This means that the actual +signature value could not be determined rather than it not matching the +expected value, this is only meaningful for RSA keys. + +=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> + +the CRL signature could not be decrypted: this means that the actual signature +value could not be determined rather than it not matching the expected value. +Unused. + +=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> + +the public key in the certificate SubjectPublicKeyInfo could not be read. + +=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> + +the signature of the certificate is invalid. + +=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> + +the signature of the certificate is invalid. + +=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> + +the certificate is not yet valid: the notBefore date is after the current time. + +=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> + +the certificate has expired: that is the notAfter date is before the current time. + +=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> + +the CRL is not yet valid. + +=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> + +the CRL has expired. + +=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> + +the certificate notBefore field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> + +the certificate notAfter field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> + +the CRL lastUpdate field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> + +the CRL nextUpdate field contains an invalid time. + +=item B<X509_V_ERR_OUT_OF_MEM: out of memory> + +an error occurred trying to allocate memory. This should never happen. + +=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> + +the passed certificate is self signed and the same certificate cannot be found +in the list of trusted certificates. + +=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> + +the certificate chain could be built up using the untrusted certificates but +the root could not be found locally. + +=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> + +the issuer certificate of a locally looked up certificate could not be found. +This normally means the list of trusted certificates is not complete. + +=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> + +no signatures could be verified because the chain contains only one certificate +and it is not self signed. + +=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> + +the certificate chain length is greater than the supplied maximum depth. Unused. + +=item B<X509_V_ERR_CERT_REVOKED: certificate revoked> + +the certificate has been revoked. + +=item B<X509_V_ERR_INVALID_CA: invalid CA certificate> + +a CA certificate is invalid. Either it is not a CA or its extensions are not +consistent with the supplied purpose. + +=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> + +the basicConstraints path-length parameter has been exceeded. + +=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> + +the supplied certificate cannot be used for the specified purpose. + +=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> + +the root CA is not marked as trusted for the specified purpose. + +=item B<X509_V_ERR_CERT_REJECTED: certificate rejected> + +the root CA is marked to reject the specified purpose. + +=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> + +the current candidate issuer certificate was rejected because its subject name +did not match the issuer name of the current certificate. This is only set +if issuer check debugging is enabled it is used for status notification and +is B<not> in itself an error. + +=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> + +the current candidate issuer certificate was rejected because its subject key +identifier was present and did not match the authority key identifier current +certificate. This is only set if issuer check debugging is enabled it is used +for status notification and is B<not> in itself an error. + +=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> + +the current candidate issuer certificate was rejected because its issuer name +and serial number was present and did not match the authority key identifier of +the current certificate. This is only set if issuer check debugging is enabled +it is used for status notification and is B<not> in itself an error. + +=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> + +the current candidate issuer certificate was rejected because its keyUsage +extension does not permit certificate signing. This is only set if issuer check +debugging is enabled it is used for status notification and is B<not> in itself +an error. + +=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension> + +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. + + +=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension> + +A certificate policies extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. This error only +occurs if policy processing is enabled. + +=item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy> + +The verification flags were set to require and explicit policy but none was +present. + +=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope> + +The only CRLs that could be found did not match the scope of the certificate. + +=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature> + +Some feature of a certificate extension is not supported. Unused. + +=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation> + +A name constraint violation occurred in the permitted subtrees. + +=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation> + +A name constraint violation occurred in the excluded subtrees. + +=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported> + +A certificate name constraints extension included a minimum or maximum field: +this is not supported. + +=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type> + +An unsupported name constraint type was encountered. OpenSSL currently only +supports directory name, DNS name, email and URI types. + +=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax> + +The format of the name constraint is not recognised: for example an email +address format of a form not mentioned in RFC3280. This could be caused by +a garbage extension or some new feature not currently supported. + +=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error> + +An error occurred when attempting to verify the CRL path. This error can only +happen if extended CRL checking is enabled. + +=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> + +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 +in the B<X509_VERIFY_CTX> structure. + +In versions of OpenSSL before 1.0 the current certificate returned by +X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should +check the return value before printing out any debugging information relating +to the current certificate. + +If an unrecognised error code is passed to X509_verify_cert_error_string() the +numerical value of the unknown code is returned in a static buffer. This is not +thread safe but will never happen unless an invalid code is passed. + +=head1 SEE ALSO + +L<X509_verify_cert(3)>, +L<X509_up_ref(3)>, +L<X509_free(3)>. + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_new.pod b/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_new.pod new file mode 100644 index 0000000..2828ed7 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_new.pod @@ -0,0 +1,174 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, +X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert, +X509_STORE_CTX_set0_crls, +X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, +X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, +X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, +X509_STORE_CTX_get_num_untrusted, +X509_STORE_CTX_set_default, +X509_STORE_CTX_set_verify, +X509_STORE_CTX_verify_fn +- X509_STORE_CTX initialisation + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + X509_STORE_CTX *X509_STORE_CTX_new(void); + void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); + void X509_STORE_CTX_free(X509_STORE_CTX *ctx); + + int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, + X509 *x509, STACK_OF(X509) *chain); + + void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); + + void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x); + STACK_OF(X509) *X509_STORE_CTX_get0_chain(X609_STORE_CTX *ctx); + void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain); + void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); + + X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); + int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); + + STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); + + int X509_STORE_CTX_get_num_untrusted(X509_STORE_CTX *ctx); + + typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *); + void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify); + +=head1 DESCRIPTION + +These functions initialise an B<X509_STORE_CTX> structure for subsequent use +by X509_verify_cert(). + +X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure. + +X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure. +The context can then be reused with an new call to X509_STORE_CTX_init(). + +X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx> +is no longer valid. +If B<ctx> is NULL nothing is done. + +X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation. +It must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only +good for one call to X509_verify_cert(); if you want to verify a second +certificate with the same B<ctx> then you must call X509_STORE_CTX_cleanup() +and then X509_STORE_CTX_init() again before the second call to +X509_verify_cert(). The trusted certificate store is set to B<store>, the end +entity certificate to be verified is set to B<x509> and a set of additional +certificates (which will be untrusted but may be used to build the chain) in +B<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be +B<NULL>. + +X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of +B<ctx> to B<sk>. This is an alternative way of specifying trusted certificates +instead of using an B<X509_STORE>. + +X509_STORE_CTX_set_cert() sets the certificate to be verified in B<ctx> to +B<x>. + +X509_STORE_CTX_set0_verified_chain() sets the validated chain used +by B<ctx> to be B<chain>. +Ownership of the chain is transferred to B<ctx> and should not be +free'd by the caller. +X509_STORE_CTX_get0_chain() returns a the internal pointer used by the +B<ctx> that contains the validated chain. + +X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate +verification to B<sk>. These CRLs will only be used if CRL verification is +enabled in the associated B<X509_VERIFY_PARAM> structure. This might be +used where additional "useful" CRLs are supplied as part of a protocol, +for example in a PKCS#7 structure. + +X509_STORE_CTX_get0_param() retrieves an internal pointer +to the verification parameters associated with B<ctx>. + +X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the +stack of untrusted certificates associated with B<ctx>. + +X509_STORE_CTX_set0_untrusted() sets the internal point to the stack +of untrusted certificates associated with B<ctx> to B<sk>. + +X509_STORE_CTX_set0_param() sets the internal verification parameter pointer +to B<param>. After this call B<param> should not be used. + +X509_STORE_CTX_set_default() looks up and sets the default verification +method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to +find an appropriate set of parameters from B<name>. + +X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates +that were used in building the chain following a call to X509_verify_cert(). + +X509_STORE_CTX_set_verify() provides the capability for overriding the default +verify function. This function is responsible for verifying chain signatures and +expiration times. + +A verify function is defined as an X509_STORE_CTX_verify type which has the +following signature: + + int (*verify)(X509_STORE_CTX *); + +This function should receive the current X509_STORE_CTX as a parameter and +return 1 on success or 0 on failure. + +=head1 NOTES + +The certificates and CRLs in a store are used internally and should B<not> +be freed up until after the associated B<X509_STORE_CTX> is freed. + +=head1 BUGS + +The certificates and CRLs in a context are used internally and should B<not> +be freed up until after the associated B<X509_STORE_CTX> is freed. Copies +should be made or reference counts increased instead. + +=head1 RETURN VALUES + +X509_STORE_CTX_new() returns an newly allocates context or B<NULL> is an +error occurred. + +X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred. + +X509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM> +structure or B<NULL> if an error occurred. + +X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), +X509_STORE_CTX_set0_trusted_stack(), +X509_STORE_CTX_set_cert(), +X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return +values. + +X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred. + +X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates +used. + +=head1 SEE ALSO + +L<X509_verify_cert(3)> +L<X509_VERIFY_PARAM_set_flags(3)> + +=head1 HISTORY + +X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0 +X509_STORE_CTX_get_num_untrusted() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_set_verify_cb.pod b/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_set_verify_cb.pod new file mode 100644 index 0000000..3be256d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_STORE_CTX_set_verify_cb.pod @@ -0,0 +1,215 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_get_cleanup, +X509_STORE_CTX_get_lookup_crls, +X509_STORE_CTX_get_lookup_certs, +X509_STORE_CTX_get_check_policy, +X509_STORE_CTX_get_cert_crl, +X509_STORE_CTX_get_check_crl, +X509_STORE_CTX_get_get_crl, +X509_STORE_CTX_get_check_revocation, +X509_STORE_CTX_get_check_issued, +X509_STORE_CTX_get_get_issuer, +X509_STORE_CTX_get_verify_cb, +X509_STORE_CTX_set_verify_cb, +X509_STORE_CTX_verify_cb +- get and set verification callback + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *); + + X509_STORE_CTX_verify_cb X509_STORE_CTX_get_verify_cb(X509_STORE_CTX *ctx); + + void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, + X509_STORE_CTX_verify_cb verify_cb); + + X509_STORE_CTX_get_issuer_fn X509_STORE_CTX_get_get_issuer(X509_STORE_CTX *ctx); + X509_STORE_CTX_check_issued_fn X509_STORE_CTX_get_check_issued(X509_STORE_CTX *ctx); + X509_STORE_CTX_check_revocation_fn X509_STORE_CTX_get_check_revocation(X509_STORE_CTX *ctx); + X509_STORE_CTX_get_crl_fn X509_STORE_CTX_get_get_crl(X509_STORE_CTX *ctx); + X509_STORE_CTX_check_crl_fn X509_STORE_CTX_get_check_crl(X509_STORE_CTX *ctx); + X509_STORE_CTX_cert_crl_fn X509_STORE_CTX_get_cert_crl(X509_STORE_CTX *ctx); + X509_STORE_CTX_check_policy_fn X509_STORE_CTX_get_check_policy(X509_STORE_CTX *ctx); + X509_STORE_CTX_lookup_certs_fn X509_STORE_CTX_get_lookup_certs(X509_STORE_CTX *ctx); + X509_STORE_CTX_lookup_crls_fn X509_STORE_CTX_get_lookup_crls(X509_STORE_CTX *ctx); + X509_STORE_CTX_cleanup_fn X509_STORE_CTX_get_cleanup(X509_STORE_CTX *ctx); + +=head1 DESCRIPTION + +X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to +B<verify_cb> overwriting any existing callback. + +The verification callback can be used to customise the operation of certificate +verification, either by overriding error conditions or logging errors for +debugging purposes. + +However a verification callback is B<not> essential and the default operation +is often sufficient. + +The B<ok> parameter to the callback indicates the value the callback should +return to retain the default behaviour. If it is zero then an error condition +is indicated. If it is 1 then no error occurred. If the flag +B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the +policy checking is complete. + +The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that +is performing the verification operation. A callback can examine this +structure and receive additional information about the error, for example +by calling X509_STORE_CTX_get_current_cert(). Additional application data can +be passed to the callback via the B<ex_data> mechanism. + +X509_STORE_CTX_get_verify_cb() returns the value of the current callback +for the specific B<ctx>. + +X509_STORE_CTX_get_get_issuer(), +X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(), +X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(), +X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(), +X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls() +and X509_STORE_CTX_get_cleanup() return the function pointers cached +from the corresponding B<X509_STORE>, please see +L<X509_STORE_set_verify(3)> for more information. + + +=head1 WARNING + +In general a verification callback should B<NOT> unconditionally return 1 in +all circumstances because this will allow verification to succeed no matter +what the error. This effectively removes all security from the application +because B<any> certificate (including untrusted generated ones) will be +accepted. + +=head1 NOTES + +The verification callback can be set and inherited from the parent structure +performing the operation. In some cases (such as S/MIME verification) the +B<X509_STORE_CTX> structure is created and destroyed internally and the +only way to set a custom verification callback is by inheriting it from the +associated B<X509_STORE>. + +=head1 RETURN VALUES + +X509_STORE_CTX_set_verify_cb() does not return a value. + +=head1 EXAMPLES + +Default callback operation: + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + return ok; + } + +Simple example, suppose a certificate in the chain is expired and we wish +to continue after this error: + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + /* Tolerate certificate expiration */ + if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) + return 1; + /* Otherwise don't override */ + return ok; + } + +More complex example, we don't wish to continue after B<any> certificate has +expired just one specific case: + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + int err = X509_STORE_CTX_get_error(ctx); + X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); + if (err == X509_V_ERR_CERT_HAS_EXPIRED) + { + if (check_is_acceptable_expired_cert(err_cert) + return 1; + } + return ok; + } + +Full featured logging callback. In this case the B<bio_err> is assumed to be +a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using +B<ex_data>. + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + X509 *err_cert; + int err, depth; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + BIO_printf(bio_err, "depth=%d ", depth); + if (err_cert) + { + X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert), + 0, XN_FLAG_ONELINE); + BIO_puts(bio_err, "\n"); + } + else + BIO_puts(bio_err, "<no cert>\n"); + if (!ok) + BIO_printf(bio_err, "verify error:num=%d:%s\n", err, + X509_verify_cert_error_string(err)); + switch (err) + { + case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: + BIO_puts(bio_err, "issuer= "); + X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert), + 0, XN_FLAG_ONELINE); + BIO_puts(bio_err, "\n"); + break; + case X509_V_ERR_CERT_NOT_YET_VALID: + case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: + BIO_printf(bio_err, "notBefore="); + ASN1_TIME_print(bio_err, X509_get_notBefore(err_cert)); + BIO_printf(bio_err, "\n"); + break; + case X509_V_ERR_CERT_HAS_EXPIRED: + case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: + BIO_printf(bio_err, "notAfter="); + ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert)); + BIO_printf(bio_err, "\n"); + break; + case X509_V_ERR_NO_EXPLICIT_POLICY: + policies_print(bio_err, ctx); + break; + } + if (err == X509_V_OK && ok == 2) + /* print out policies */ + + BIO_printf(bio_err, "verify return:%d\n", ok); + return(ok); + } + +=head1 SEE ALSO + +L<X509_STORE_CTX_get_error(3)> +L<X509_STORE_set_verify_cb_func(3)> +L<X509_STORE_CTX_get_ex_new_index(3)> + +=head1 HISTORY + +X509_STORE_CTX_get_get_issuer(), +X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(), +X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(), +X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(), +X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls() +and X509_STORE_CTX_get_cleanup() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_STORE_get0_param.pod b/openssl-1.1.0h/doc/crypto/X509_STORE_get0_param.pod new file mode 100644 index 0000000..0aed725 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_STORE_get0_param.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +X509_STORE_get0_param, X509_STORE_set1_param, +X509_STORE_get0_objects - X509_STORE setter and getter functions + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + X509_VERIFY_PARAM *X509_STORE_get0_param(X509_STORE *ctx); + int X509_STORE_set1_param(X509_STORE *ctx, X509_VERIFY_PARAM *pm); + STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(X509_STORE *ctx); + +=head1 DESCRIPTION + +X509_STORE_set1_param() sets the verification parameters +to B<pm> for B<ctx>. + +X509_STORE_get0_param() retrieves an internal pointer to the verification +parameters for B<ctx>. The returned pointer must not be freed by the +calling application + +X509_STORE_get0_objects() retrieve an internal pointer to the store's +X509 object cache. The cache contains B<X509> and B<X509_CRL> objects. The +returned pointer must not be freed by the calling application. + + +=head1 RETURN VALUES + +X509_STORE_get0_param() returns a pointer to an +B<X509_VERIFY_PARAM> structure. + +X509_STORE_set1_param() returns 1 for success and 0 for failure. + +X509_STORE_get0_objects() returns a pointer to a stack of B<X509_OBJECT>. + +=head1 SEE ALSO + +L<X509_STORE_new(3)> + +=head1 HISTORY + +B<X509_STORE_get0_param> and B<X509_STORE_get0_objects> were added in +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_STORE_new.pod b/openssl-1.1.0h/doc/crypto/X509_STORE_new.pod new file mode 100644 index 0000000..f7a5c81 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_STORE_new.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +X509_STORE_new, X509_STORE_up_ref, X509_STORE_free, X509_STORE_lock, +X509_STORE_unlock - X509_STORE allocation, freeing and locking functions + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + X509_STORE *X509_STORE_new(void); + void X509_STORE_free(X509_STORE *v); + int X509_STORE_lock(X509_STORE *v); + int X509_STORE_unlock(X509_STORE *v); + int X509_STORE_up_ref(X509_STORE *v); + +=head1 DESCRIPTION + +The X509_STORE_new() function returns a new X509_STORE. + +X509_STORE_up_ref() increments the reference count associated with the +X509_STORE object. + +X509_STORE_lock() locks the store from modification by other threads, +X509_STORE_unlock() locks it. + +X509_STORE_free() frees up a single X509_STORE object. + +=head1 RETURN VALUES + +X509_STORE_new() returns a newly created X509_STORE or NULL if the call fails. + +X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock() return +1 for success and 0 for failure. + +X509_STORE_free() does not return values. + +=head1 SEE ALSO + +L<X509_STORE_set_verify_cb_func(3)> +L<X509_STORE_get0_param(3)> + +=head1 HISTORY + +The X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock() +functions were added in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_STORE_set_verify_cb_func.pod b/openssl-1.1.0h/doc/crypto/X509_STORE_set_verify_cb_func.pod new file mode 100644 index 0000000..12a4646 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_STORE_set_verify_cb_func.pod @@ -0,0 +1,265 @@ +=pod + +=head1 NAME + +X509_STORE_set_lookup_crls_cb, +X509_STORE_set_verify_func, +X509_STORE_get_cleanup, +X509_STORE_set_cleanup, +X509_STORE_get_lookup_crls, +X509_STORE_set_lookup_crls, +X509_STORE_get_lookup_certs, +X509_STORE_set_lookup_certs, +X509_STORE_get_check_policy, +X509_STORE_set_check_policy, +X509_STORE_get_cert_crl, +X509_STORE_set_cert_crl, +X509_STORE_get_check_crl, +X509_STORE_set_check_crl, +X509_STORE_get_get_crl, +X509_STORE_set_get_crl, +X509_STORE_get_check_revocation, +X509_STORE_set_check_revocation, +X509_STORE_get_check_issued, +X509_STORE_set_check_issued, +X509_STORE_get_get_issuer, +X509_STORE_set_get_issuer, +X509_STORE_CTX_get_verify, +X509_STORE_set_verify, +X509_STORE_get_verify_cb, +X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb, +X509_STORE_CTX_cert_crl_fn, X509_STORE_CTX_check_crl_fn, +X509_STORE_CTX_check_issued_fn, X509_STORE_CTX_check_policy_fn, +X509_STORE_CTX_check_revocation_fn, X509_STORE_CTX_cleanup_fn, +X509_STORE_CTX_get_crl_fn, X509_STORE_CTX_get_issuer_fn, +X509_STORE_CTX_lookup_certs_fn, X509_STORE_CTX_lookup_crls_fn +- set verification callback + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + typedef int (*X509_STORE_CTX_get_issuer_fn)(X509 **issuer, + X509_STORE_CTX *ctx, X509 *x); + typedef int (*X509_STORE_CTX_check_issued_fn)(X509_STORE_CTX *ctx, + X509 *x, X509 *issuer); + typedef int (*X509_STORE_CTX_check_revocation_fn)(X509_STORE_CTX *ctx); + typedef int (*X509_STORE_CTX_get_crl_fn)(X509_STORE_CTX *ctx, + X509_CRL **crl, X509 *x); + typedef int (*X509_STORE_CTX_check_crl_fn)(X509_STORE_CTX *ctx, X509_CRL *crl); + typedef int (*X509_STORE_CTX_cert_crl_fn)(X509_STORE_CTX *ctx, + X509_CRL *crl, X509 *x); + typedef int (*X509_STORE_CTX_check_policy_fn)(X509_STORE_CTX *ctx); + typedef STACK_OF(X509) *(*X509_STORE_CTX_lookup_certs_fn)(X509_STORE_CTX *ctx, + X509_NAME *nm); + typedef STACK_OF(X509_CRL) *(*X509_STORE_CTX_lookup_crls_fn)(X509_STORE_CTX *ctx, + X509_NAME *nm); + typedef int (*X509_STORE_CTX_cleanup_fn)(X509_STORE_CTX *ctx); + + void X509_STORE_set_verify_cb(X509_STORE *ctx, + X509_STORE_CTX_verify_cb verify_cb); + X509_STORE_CTX_verify_cb X509_STORE_get_verify_cb(X509_STORE_CTX *ctx); + + void X509_STORE_set_verify(X509_STORE *ctx, X509_STORE_CTX_verify_fn verify); + X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx); + + void X509_STORE_set_get_issuer(X509_STORE *ctx, + X509_STORE_CTX_get_issuer_fn get_issuer); + X509_STORE_CTX_get_issuer_fn X509_STORE_get_get_issuer(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_issued(X509_STORE *ctx, + X509_STORE_CTX_check_issued_fn check_issued); + X509_STORE_CTX_check_issued_fn X509_STORE_get_check_issued(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_revocation(X509_STORE *ctx, + X509_STORE_CTX_check_revocation_fn check_revocation); + X509_STORE_CTX_check_revocation_fn X509_STORE_get_check_revocation(X509_STORE_CTX *ctx); + + void X509_STORE_set_get_crl(X509_STORE *ctx, + X509_STORE_CTX_get_crl_fn get_crl); + X509_STORE_CTX_get_crl_fn X509_STORE_get_get_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_crl(X509_STORE *ctx, + X509_STORE_CTX_check_crl_fn check_crl); + X509_STORE_CTX_check_crl_fn X509_STORE_get_check_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_cert_crl(X509_STORE *ctx, + X509_STORE_CTX_cert_crl_fn cert_crl); + X509_STORE_CTX_cert_crl_fn X509_STORE_get_cert_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_policy(X509_STORE *ctx, + X509_STORE_CTX_check_policy_fn check_policy); + X509_STORE_CTX_check_policy_fn X509_STORE_get_check_policy(X509_STORE_CTX *ctx); + + void X509_STORE_set_lookup_certs(X509_STORE *ctx, + X509_STORE_CTX_lookup_certs_fn lookup_certs); + X509_STORE_CTX_lookup_certs_fn X509_STORE_get_lookup_certs(X509_STORE_CTX *ctx); + + void X509_STORE_set_lookup_crls(X509_STORE *ctx, + X509_STORE_CTX_lookup_crls_fn lookup_crls); + X509_STORE_CTX_lookup_crls_fn X509_STORE_get_lookup_crls(X509_STORE_CTX *ctx); + + void X509_STORE_set_cleanup(X509_STORE *ctx, + X509_STORE_CTX_cleanup_fn cleanup); + X509_STORE_CTX_cleanup_fn X509_STORE_get_cleanup(X509_STORE_CTX *ctx); + + /* Aliases */ + void X509_STORE_set_verify_cb_func(X509_STORE *st, + X509_STORE_CTX_verify_cb verify_cb); + void X509_STORE_set_verify_func(X509_STORE *ctx, + X509_STORE_CTX_verify_fn verify); + void X509_STORE_set_lookup_crls_cb(X509_STORE *ctx, + X509_STORE_CTX_lookup_crls_fn lookup_crls); + +=head1 DESCRIPTION + +X509_STORE_set_verify_cb() sets the verification callback of B<ctx> to +B<verify_cb> overwriting the previous callback. +The callback assigned with this function becomes a default for the one +that can be assigned directly to the corresponding B<X509_STORE_CTX>, +please see L<X509_STORE_CTX_set_verify_cb(3)> for further information. + +X509_STORE_set_verify() sets the final chain verification function for +B<ctx> to B<verify>. +Its purpose is to go through the chain of certificates and check that +all signatures are valid and that the current time is within the +limits of each certificate's first and last validity time. +The final chain verification functions must return 0 on failure and 1 +on success. +I<If no chain verification function is provided, the internal default +function will be used instead.> + +X509_STORE_set_get_issuer() sets the function to get the issuer +certificate that verifies the given certificate B<x>. +When found, the issuer certificate must be assigned to B<*issuer>. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_check_issued() sets the function to check that a given +certificate B<x> is issued with the issuer certificate B<issuer>. +This function must return 0 on failure (among others if B<x> hasn't +been issued with B<issuer>) and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_check_revocation() sets the revocation checking +function. +Its purpose is to look through the final chain and check the +revocation status for each certificate. +It must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_get_crl() sets the function to get the crl for a given +certificate B<x>. +When found, the crl must be assigned to B<*crl>. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_check_crl() sets the function to check the validity of +the given B<crl>. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_cert_crl() sets the function to check the revocation +status of the given certificate B<x> against the given B<crl>. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_check_policy() sets the function to check the policies +of all the certificates in the final chain.. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_lookup_certs() and X509_STORE_set_lookup_crls() set the +functions to look up all the certs or all the CRLs that match the +given name B<nm>. +These functions return NULL on failure and a pointer to a stack of +certificates (B<X509>) or to a stack of CRLs (B<X509_CRL>) on +success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_cleanup() sets the final cleanup function, which is +called when the context (B<X509_STORE_CTX>) is being torn down. +This function doesn't return any value. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_get_verify_cb(), X509_STORE_CTX_get_verify(), +X509_STORE_get_get_issuer(), X509_STORE_get_check_issued(), +X509_STORE_get_check_revocation(), X509_STORE_get_get_crl(), +X509_STORE_get_check_crl(), X509_STORE_set_verify(), +X509_STORE_set_get_issuer(), X509_STORE_get_cert_crl(), +X509_STORE_get_check_policy(), X509_STORE_get_lookup_certs(), +X509_STORE_get_lookup_crls() and X509_STORE_get_cleanup() all return +the function pointer assigned with X509_STORE_set_check_issued(), +X509_STORE_set_check_revocation(), X509_STORE_set_get_crl(), +X509_STORE_set_check_crl(), X509_STORE_set_cert_crl(), +X509_STORE_set_check_policy(), X509_STORE_set_lookup_certs(), +X509_STORE_set_lookup_crls() and X509_STORE_set_cleanup(), or NULL if +no assignment has been made. + +X509_STORE_set_verify_cb_func(), X509_STORE_set_verify_func() and +X509_STORE_set_lookup_crls_cb() are aliases for +X509_STORE_set_verify_cb(), X509_STORE_set_verify() and +X509_STORE_set_lookup_crls, available as macros for backward +compatibility. + +=head1 NOTES + +All the callbacks from a B<X509_STORE> are inherited by the +corresponding B<X509_STORE_CTX> structure when it is initialized. +See L<X509_STORE_CTX_set_verify_cb(3)> for further details. + +=head1 BUGS + +The macro version of this function was the only one available before +OpenSSL 1.0.0. + +=head1 RETURN VALUES + +The X509_STORE_set_*() functions do not return a value. + +The X509_STORE_get_*() functions return a pointer of the appropriate +function type. + +=head1 SEE ALSO + +L<X509_STORE_CTX_set_verify_cb(3)>, L<X509_STORE_CTX_get0_chain(3)>, +L<X509_STORE_CTX_verify_cb(3)>, L<X509_STORE_CTX_verify_fn(3)>, +L<CMS_verify(3)> + +=head1 HISTORY + +X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0. + +X509_STORE_set_verify_cb(), X509_STORE_get_verify_cb(), +X509_STORE_set_verify(), X509_STORE_CTX_get_verify(), +X509_STORE_set_get_issuer(), X509_STORE_get_get_issuer(), +X509_STORE_set_check_issued(), X509_STORE_get_check_issued(), +X509_STORE_set_check_revocation(), X509_STORE_get_check_revocation(), +X509_STORE_set_get_crl(), X509_STORE_get_get_crl(), +X509_STORE_set_check_crl(), X509_STORE_get_check_crl(), +X509_STORE_set_cert_crl(), X509_STORE_get_cert_crl(), +X509_STORE_set_check_policy(), X509_STORE_get_check_policy(), +X509_STORE_set_lookup_certs(), X509_STORE_get_lookup_certs(), +X509_STORE_set_lookup_crls(), X509_STORE_get_lookup_crls(), +X509_STORE_set_cleanup() and X509_STORE_get_cleanup() were added in +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/openssl-1.1.0h/doc/crypto/X509_VERIFY_PARAM_set_flags.pod new file mode 100644 index 0000000..5263fac --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_VERIFY_PARAM_set_flags.pod @@ -0,0 +1,359 @@ +=pod + +=head1 NAME + +X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, +X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, +X509_VERIFY_PARAM_get_inh_flags, X509_VERIFY_PARAM_set_inh_flags, +X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, +X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, +X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time, +X509_VERIFY_PARAM_get_time, +X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, +X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, +X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, +X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, +X509_VERIFY_PARAM_set1_ip_asc +- X509 verification parameters + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, + unsigned long flags); + int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, + unsigned long flags); + unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); + + int X509_VERIFY_PARAM_set_inh_flags(X509_VERIFY_PARAM *param, + uint32_t flags); + uint32_t X509_VERIFY_PARAM_get_inh_flags(const X509_VERIFY_PARAM *param); + + int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); + int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); + + void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); + time_t X509_VERIFY_PARAM_get_time(const X509_VERIFY_PARAM *param); + + int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, + ASN1_OBJECT *policy); + int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, + STACK_OF(ASN1_OBJECT) *policies); + + void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); + int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); + + void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param, + int auth_level); + int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param); + + int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, + const char *name, size_t namelen); + int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param, + const char *name, size_t namelen); + void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param, + unsigned int flags); + char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param); + int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, + const char *email, size_t emaillen); + int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, + const unsigned char *ip, size_t iplen); + int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc); + +=head1 DESCRIPTION + +These functions manipulate the B<X509_VERIFY_PARAM> structure associated with +a certificate verification operation. + +The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring +it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete +description of values the B<flags> parameter can take. + +X509_VERIFY_PARAM_get_flags() returns the flags in B<param>. + +X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in B<param> +which specifies how verification flags are copied from one structure to +another. X509_VERIFY_PARAM_set_inh_flags() sets the inheritance flags. +See the B<INHERITANCE FLAGS> section for a description of these bits. + +X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>. + +X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param> +to B<purpose>. This determines the acceptable purpose of the certificate +chain, for example SSL client or SSL server. + +X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to +B<trust>. + +X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to +B<t>. Normally the current time is used. + +X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled +by default) and adds B<policy> to the acceptable policy set. + +X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled +by default) and sets the acceptable policy set to B<policies>. Any existing +policy set is cleared. The B<policies> parameter can be B<NULL> to clear +an existing policy set. + +X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>. +That is the maximum number of intermediate CA certificates that can appear in a +chain. +A maximal depth chain contains 2 more certificates than the limit, since +neither the end-entity certificate nor the trust-anchor count against this +limit. +Thus a B<depth> limit of 0 only allows the end-entity certificate to be signed +directly by the trust-anchor, while with a B<depth> limit of 1 there can be one +intermediate CA certificate between the trust-anchor and the end-entity +certificate. + +X509_VERIFY_PARAM_set_auth_level() sets the authentication security level to +B<auth_level>. +The authentication security level determines the acceptable signature and public +key strength when verifying certificate chains. +For a certificate chain to validate, the public keys of all the certificates +must meet the specified security level. +The signature algorithm security level is not enforced for the chain's I<trust +anchor> certificate, which is either directly trusted or validated by means other +than its signature. +See L<SSL_CTX_set_security_level(3)> for the definitions of the available +levels. +The default security level is -1, or "not set". +At security level 0 or lower all algorithms are acceptable. +Security level 1 requires at least 80-bit-equivalent security and is broadly +interoperable, though it will, for example, reject MD5 signatures or RSA keys +shorter than 1024 bits. + +X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to +B<name> clearing any previously specified host name or names. If +B<name> is NULL, or empty the list of hostnames is cleared, and +name checks are not performed on the peer certificate. If B<name> +is NUL-terminated, B<namelen> may be zero, otherwise B<namelen> +must be set to the length of B<name>. When a hostname is specified, +certificate verification automatically invokes L<X509_check_host(3)> +with flags equal to the B<flags> argument given to +X509_VERIFY_PARAM_set_hostflags() (default zero). Applications +are strongly advised to use this interface in preference to explicitly +calling L<X509_check_host(3)>, hostname checks are out of scope +with the DANE-EE(3) certificate usage, and the internal check will +be suppressed as appropriate when DANE support is added to OpenSSL. + +X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference +identifier that can match the peer's certificate. Any previous names +set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host() +are retained, no change is made if B<name> is NULL or empty. When +multiple names are configured, the peer is considered verified when +any name matches. + +X509_VERIFY_PARAM_get0_peername() returns the DNS hostname or subject +CommonName from the peer certificate that matched one of the reference +identifiers. When wildcard matching is not disabled, or when a +reference identifier specifies a parent domain (starts with ".") +rather than a hostname, the peer name may be a wildcard name or a +sub-domain of the reference identifier respectively. The return +string is allocated by the library and is no longer valid once the +associated B<param> argument is freed. Applications must not free +the return value. + +X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to +B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise +B<emaillen> must be set to the length of B<email>. When an email address +is specified, certificate verification automatically invokes +L<X509_check_email(3)>. + +X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>. +The B<ip> argument is in binary format, in network byte-order and +B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP +address is specified, certificate verification automatically invokes +L<X509_check_ip(3)>. + +X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to +B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string: +dotted decimal quad for IPv4 and colon-separated hexadecimal for +IPv6. The condensed "::" notation is supported for IPv6 addresses. + +=head1 RETURN VALUES + +X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), +X509_VERIFY_PARAM_set_inh_flags(), +X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), +X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(), +X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(), +X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and +X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for +failure. + +X509_VERIFY_PARAM_get_flags() returns the current verification flags. + +X509_VERIFY_PARAM_get_inh_flags() returns the current inheritance flags. + +X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return +values. + +X509_VERIFY_PARAM_get_depth() returns the current verification depth. + +X509_VERIFY_PARAM_get_auth_level() returns the current authentication security +level. + +=head1 VERIFICATION FLAGS + +The verification flags consists of zero or more of the following flags +ored together. + +B<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf +certificate. An error occurs if a suitable CRL cannot be found. + +B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate +chain. + +B<X509_V_FLAG_IGNORE_CRITICAL> disabled critical extension checking. By default +any unhandled critical extensions in certificates or (if checked) CRLs results +in a fatal error. If this flag is set unhandled critical extensions are +ignored. B<WARNING> setting this option for anything other than debugging +purposes can be a security risk. Finer control over which extensions are +supported can be performed in the verification callback. + +The B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken +certificates and makes the verification strictly apply B<X509> rules. + +B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification. + +B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default +no policy checking is performed. Additional information is sent to the +verification callback relating to policy checking. + +B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and +B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any +policy> and B<inhibit policy mapping> flags respectively as defined in +B<RFC3280>. Policy checking is automatically enabled if any of these flags +are set. + +If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful +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 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. + +If B<X509_V_FLAG_USE_DELTAS> is set delta CRLs (if present) are used to +determine certificate status. If not set deltas are ignored. + +B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed +certificate signature. By default this check is disabled because it doesn't +add any additional security but in some cases applications might want to +check the signature anyway. A side effect of not checking the root CA +signature is that disabled or unsupported message digests on the root CA +are not treated as fatal errors. + +When B<X509_V_FLAG_TRUSTED_FIRST> is set, construction of the certificate chain +in L<X509_verify_cert(3)> will search the trust store for issuer certificates +before searching the provided untrusted certificates. +Local issuer certificates are often more likely to satisfy local security +requirements and lead to a locally trusted root. +This is especially important when some certificates in the trust store have +explicit trust settings (see "TRUST SETTINGS" in L<x509(1)>). +As of OpenSSL 1.1.0 this option is on by default. + +The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative +chains. +By default, unless B<X509_V_FLAG_TRUSTED_FIRST> is set, when building a +certificate chain, if the first certificate chain found is not trusted, then +OpenSSL will attempt to replace untrusted certificates supplied by the peer +with certificates from the trust store to see if an alternative chain can be +found that is trusted. +As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option +has no effect. + +The B<X509_V_FLAG_PARTIAL_CHAIN> flag causes intermediate certificates in the +trust store to be treated as trust-anchors, in the same way as the self-signed +root CA certificates. +This makes it possible to trust certificates issued by an intermediate CA +without having to trust its ancestor root CA. +With OpenSSL 1.1.0 and later and <X509_V_FLAG_PARTIAL_CHAIN> set, chain +construction stops as soon as the first certificate from the trust store is +added to the chain, whether that certificate is a self-signed "root" +certificate or a not self-signed intermediate certificate. +Thus, when an intermediate certificate is found in the trust store, the +verified chain passed to callbacks may be shorter than it otherwise would +be without the B<X509_V_FLAG_PARTIAL_CHAIN> flag. + +The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period +of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time() +is used to specify a verification time, the check is not suppressed. + +=head1 INHERITANCE FLAGS + +These flags specify how parameters are "inherited" from one structure to +another. + +If B<X509_VP_FLAG_ONCE> is set then the current setting is zeroed +after the next call. + +If B<X509_VP_FLAG_LOCKED> is set then no values are copied. This overrides +all of the following flags. + +If B<X509_VP_FLAG_DEFAULT> is set then anything set in the source is copied +to the destination. Effectively the values in "to" become default values +which will be used only if nothing new is set in "from". This is the +default. + +If B<X509_VP_FLAG_OVERWRITE> is set then all value are copied across whether +they are set or not. Flags is still Ored though. + +If B<X509_VP_FLAG_RESET_FLAGS> is set then the flags value is copied instead +of ORed. + +=head1 NOTES + +The above functions should be used to manipulate verification parameters +instead of legacy functions which work in specific structures such as +X509_STORE_CTX_set_flags(). + +=head1 BUGS + +Delta CRL checking is currently primitive. Only a single delta can be used and +(partly due to limitations of B<X509_STORE>) constructed CRLs are not +maintained. + +If CRLs checking is enable CRLs are expected to be available in the +corresponding B<X509_STORE> structure. No attempt is made to download +CRLs from the CRL distribution points extension. + +=head1 EXAMPLE + +Enable CRL checking when performing certificate verification during SSL +connections associated with an B<SSL_CTX> structure B<ctx>: + + X509_VERIFY_PARAM *param; + param = X509_VERIFY_PARAM_new(); + X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); + SSL_CTX_set1_param(ctx, param); + X509_VERIFY_PARAM_free(param); + +=head1 SEE ALSO + +L<X509_verify_cert(3)>, +L<X509_check_host(3)>, +L<X509_check_email(3)>, +L<X509_check_ip(3)>, +L<x509(1)> + +=head1 HISTORY + +The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0 +The legacy B<X509_V_FLAG_CB_ISSUER_CHECK> flag is deprecated as of +OpenSSL 1.1.0, and has no effect. + +=head1 COPYRIGHT + +Copyright 2009-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_check_ca.pod b/openssl-1.1.0h/doc/crypto/X509_check_ca.pod new file mode 100644 index 0000000..b79efb5 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_check_ca.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +X509_check_ca - check if given certificate is CA certificate + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + int X509_check_ca(X509 *cert); + +=head1 DESCRIPTION + +This function checks if given certificate is CA certificate (can be used +to sign other certificates). + +=head1 RETURN VALUE + +Function return 0, if it is not CA certificate, 1 if it is proper X509v3 +CA certificate with B<basicConstraints> extension CA:TRUE, +3, if it is self-signed X509 v1 certificate, 4, if it is certificate with +B<keyUsage> extension with bit B<keyCertSign> set, but without +B<basicConstraints>, and 5 if it has outdated Netscape Certificate Type +extension telling that it is CA certificate. + +Actually, any non-zero value means that this certificate could have been +used to sign other certificates. + +=head1 SEE ALSO + +L<X509_verify_cert(3)>, +L<X509_check_issued(3)>, +L<X509_check_purpose(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_check_host.pod b/openssl-1.1.0h/doc/crypto/X509_check_host.pod new file mode 100644 index 0000000..9384815 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_check_host.pod @@ -0,0 +1,157 @@ +=pod + +=head1 NAME + +X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_check_host(X509 *, const char *name, size_t namelen, + unsigned int flags, char **peername); + int X509_check_email(X509 *, const char *address, size_t addresslen, + unsigned int flags); + int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen, + unsigned int flags); + int X509_check_ip_asc(X509 *, const char *address, unsigned int flags); + +=head1 DESCRIPTION + +The certificate matching functions are used to check whether a +certificate matches a given host name, email address, or IP address. +The validity of the certificate and its trust level has to be checked by +other means. + +X509_check_host() checks if the certificate Subject Alternative +Name (SAN) or Subject CommonName (CN) matches the specified host +name, which must be encoded in the preferred name syntax described +in section 3.5 of RFC 1034. By default, wildcards are supported +and they match only in the left-most label; but they may match +part of that label with an explicit prefix or suffix. For example, +by default, the host B<name> "www.example.com" would match a +certificate with a SAN or CN value of "*.example.com", "w*.example.com" +or "*w.example.com". + +Per section 6.4.2 of RFC 6125, B<name> values representing international +domain names must be given in A-label form. The B<namelen> argument +must be the number of characters in the name string or zero in which +case the length is calculated with strlen(B<name>). When B<name> starts +with a dot (e.g ".example.com"), it will be matched by a certificate +valid for any sub-domain of B<name>, (see also +B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> below). + +When the certificate is matched, and B<peername> is not NULL, a +pointer to a copy of the matching SAN or CN from the peer certificate +is stored at the address passed in B<peername>. The application +is responsible for freeing the peername via OPENSSL_free() when it +is no longer needed. + +X509_check_email() checks if the certificate matches the specified +email B<address>. Only the mailbox syntax of RFC 822 is supported, +comments are not allowed, and no attempt is made to normalize quoted +characters. The B<addresslen> argument must be the number of +characters in the address string or zero in which case the length +is calculated with strlen(B<address>). + +X509_check_ip() checks if the certificate matches a specified IPv4 or +IPv6 address. The B<address> array is in binary format, in network +byte order. The length is either 4 (IPv4) or 16 (IPv6). Only +explicitly marked addresses in the certificates are considered; IP +addresses stored in DNS names and Common Names are ignored. + +X509_check_ip_asc() is similar, except that the NUL-terminated +string B<address> is first converted to the internal representation. + +The B<flags> argument is usually 0. It can be the bitwise OR of the +flags: + +=over 4 + +=item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>, + +=item B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT>, + +=item B<X509_CHECK_FLAG_NO_WILDCARDS>, + +=item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>, + +=item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>. + +=item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>. + +=back + +The B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function +to consider the subject DN even if the certificate contains at least +one subject alternative name of the right type (DNS name or email +address as appropriate); the default is to ignore the subject DN +when at least one corresponding subject alternative names is present. + +The B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT> flag causes the function to never +consider the subject DN even if the certificate contains no subject alternative +names of the right type (DNS name or email address as appropriate); the default +is to use the subject DN when no corresponding subject alternative names are +present. + +If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard +expansion; this only applies to B<X509_check_host>. + +If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support +for "*" as wildcard pattern in labels that have a prefix or suffix, +such as: "www*" or "*www"; this only applies to B<X509_check_host>. + +If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that +constitutes the complete label of a DNS name (e.g. "*.example.com") +to match more than one label in B<name>; this flag only applies +to B<X509_check_host>. + +If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name> +values which start with ".", that would otherwise match any sub-domain +in the peer certificate, to only match direct child sub-domains. +Thus, for instance, with this flag set a B<name> of ".example.com" +would match a peer certificate with a DNS name of "www.example.com", +but would not match a peer certificate with a DNS name of +"www.sub.example.com"; this flag only applies to B<X509_check_host>. + +=head1 RETURN VALUES + +The functions return 1 for a successful match, 0 for a failed match +and -1 for an internal error: typically a memory allocation failure +or an ASN.1 decoding error. + +All functions can also return -2 if the input is malformed. For example, +X509_check_host() returns -2 if the provided B<name> contains embedded +NULs. + +=head1 NOTES + +Applications are encouraged to use X509_VERIFY_PARAM_set1_host() +rather than explicitly calling L<X509_check_host(3)>. Host name +checks are out of scope with the DANE-EE(3) certificate usage, +and the internal checks will be suppressed as appropriate when +DANE support is added to OpenSSL. + +=head1 SEE ALSO + +L<SSL_get_verify_result(3)>, +L<X509_VERIFY_PARAM_set1_host(3)>, +L<X509_VERIFY_PARAM_add1_host(3)>, +L<X509_VERIFY_PARAM_set1_email(3)>, +L<X509_VERIFY_PARAM_set1_ip(3)>, +L<X509_VERIFY_PARAM_set1_ipasc(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_check_issued.pod b/openssl-1.1.0h/doc/crypto/X509_check_issued.pod new file mode 100644 index 0000000..8e4b111 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_check_issued.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +X509_check_issued - checks if certificate is issued by another +certificate + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + int X509_check_issued(X509 *issuer, X509 *subject); + + +=head1 DESCRIPTION + +This function checks if certificate I<subject> was issued using CA +certificate I<issuer>. This function takes into account not only +matching of issuer field of I<subject> with subject field of I<issuer>, +but also compares B<authorityKeyIdentifier> extension of I<subject> with +B<subjectKeyIdentifier> of I<issuer> if B<authorityKeyIdentifier> +present in the I<subject> certificate and checks B<keyUsage> field of +I<issuer>. + +=head1 RETURN VALUE + +Function return B<X509_V_OK> if certificate I<subject> is issued by +I<issuer> or some B<X509_V_ERR*> constant to indicate an error. + +=head1 SEE ALSO + +L<X509_verify_cert(3)>, +L<X509_check_ca(3)>, +L<verify(1)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_digest.pod b/openssl-1.1.0h/doc/crypto/X509_digest.pod new file mode 100644 index 0000000..3c76c8f --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_digest.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +X509_digest, X509_CRL_digest, +X509_pubkey_digest, +X509_NAME_digest, +X509_REQ_digest, +PKCS7_ISSUER_AND_SERIAL_digest +- get digest of various objects + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_digest(const X509 *data, const EVP_MD *type, unsigned char *md, + unsigned int *len); + + int X509_CRL_digest(const X509_CRL *data, const EVP_MD *type, unsigned char *md, + unsigned int *len); + + int X509_pubkey_digest(const X509 *data, const EVP_MD *type, + unsigned char *md, unsigned int *len); + + int X509_REQ_digest(const X509_REQ *data, const EVP_MD *type, + unsigned char *md, unsigned int *len); + + int X509_NAME_digest(const X509_NAME *data, const EVP_MD *type, + unsigned char *md, unsigned int *len); + + int PKCS7_ISSUER_AND_SERIAL_digest(PKCS7_ISSUER_AND_SERIAL *data, + const EVP_MD *type, unsigned char *md, + unsigned int *len); + +=head1 DESCRIPTION + +X509_pubkey_digest() returns a digest of the DER representation of the public +key in the specified X509 B<data> object. +All other functions described here return a digest of the DER representation +of their entire B<data> objects. + +The B<type> parameter specifies the digest to +be used, such as EVP_sha1(). The B<md> is a pointer to the buffer where the +digest will be copied and is assumed to be large enough; the constant +B<EVP_MAX_MD_SIZE> is suggested. The B<len> parameter, if not NULL, points +to a place where the digest size will be stored. + +=head1 RETURN VALUES + +All functions described here return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<EVP_sha1(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_dup.pod b/openssl-1.1.0h/doc/crypto/X509_dup.pod new file mode 100644 index 0000000..c5d01b2 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_dup.pod @@ -0,0 +1,303 @@ +=pod + +=head1 NAME + +DECLARE_ASN1_FUNCTIONS, +IMPLEMENT_ASN1_FUNCTIONS, +ASN1_ITEM, +ACCESS_DESCRIPTION_free, +ACCESS_DESCRIPTION_new, +ASIdOrRange_free, +ASIdOrRange_new, +ASIdentifierChoice_free, +ASIdentifierChoice_new, +ASIdentifiers_free, +ASIdentifiers_new, +ASRange_free, +ASRange_new, +AUTHORITY_INFO_ACCESS_free, +AUTHORITY_INFO_ACCESS_new, +AUTHORITY_KEYID_free, +AUTHORITY_KEYID_new, +BASIC_CONSTRAINTS_free, +BASIC_CONSTRAINTS_new, +CERTIFICATEPOLICIES_free, +CERTIFICATEPOLICIES_new, +CMS_ContentInfo_free, +CMS_ContentInfo_new, +CMS_ContentInfo_print_ctx, +CMS_ReceiptRequest_free, +CMS_ReceiptRequest_new, +CRL_DIST_POINTS_free, +CRL_DIST_POINTS_new, +DIRECTORYSTRING_free, +DIRECTORYSTRING_new, +DISPLAYTEXT_free, +DISPLAYTEXT_new, +DIST_POINT_NAME_free, +DIST_POINT_NAME_new, +DIST_POINT_free, +DIST_POINT_new, +DSAparams_dup, +ECPARAMETERS_free, +ECPARAMETERS_new, +ECPKPARAMETERS_free, +ECPKPARAMETERS_new, +EDIPARTYNAME_free, +EDIPARTYNAME_new, +ESS_CERT_ID_dup, +ESS_CERT_ID_free, +ESS_CERT_ID_new, +ESS_ISSUER_SERIAL_dup, +ESS_ISSUER_SERIAL_free, +ESS_ISSUER_SERIAL_new, +ESS_SIGNING_CERT_dup, +ESS_SIGNING_CERT_free, +ESS_SIGNING_CERT_new, +EXTENDED_KEY_USAGE_free, +EXTENDED_KEY_USAGE_new, +GENERAL_NAMES_free, +GENERAL_NAMES_new, +GENERAL_NAME_dup, +GENERAL_NAME_free, +GENERAL_NAME_new, +GENERAL_SUBTREE_free, +GENERAL_SUBTREE_new, +IPAddressChoice_free, +IPAddressChoice_new, +IPAddressFamily_free, +IPAddressFamily_new, +IPAddressOrRange_free, +IPAddressOrRange_new, +IPAddressRange_free, +IPAddressRange_new, +ISSUING_DIST_POINT_free, +ISSUING_DIST_POINT_new, +NAME_CONSTRAINTS_free, +NAME_CONSTRAINTS_new, +NETSCAPE_CERT_SEQUENCE_free, +NETSCAPE_CERT_SEQUENCE_new, +NETSCAPE_SPKAC_free, +NETSCAPE_SPKAC_new, +NETSCAPE_SPKI_free, +NETSCAPE_SPKI_new, +NOTICEREF_free, +NOTICEREF_new, +OCSP_BASICRESP_free, +OCSP_BASICRESP_new, +OCSP_CERTID_dup, +OCSP_CERTID_new, +OCSP_CERTSTATUS_free, +OCSP_CERTSTATUS_new, +OCSP_CRLID_free, +OCSP_CRLID_new, +OCSP_ONEREQ_free, +OCSP_ONEREQ_new, +OCSP_REQINFO_free, +OCSP_REQINFO_new, +OCSP_RESPBYTES_free, +OCSP_RESPBYTES_new, +OCSP_RESPDATA_free, +OCSP_RESPDATA_new, +OCSP_RESPID_free, +OCSP_RESPID_new, +OCSP_RESPONSE_new, +OCSP_REVOKEDINFO_free, +OCSP_REVOKEDINFO_new, +OCSP_SERVICELOC_free, +OCSP_SERVICELOC_new, +OCSP_SIGNATURE_free, +OCSP_SIGNATURE_new, +OCSP_SINGLERESP_free, +OCSP_SINGLERESP_new, +OTHERNAME_free, +OTHERNAME_new, +PBE2PARAM_free, +PBE2PARAM_new, +PBEPARAM_free, +PBEPARAM_new, +PBKDF2PARAM_free, +PBKDF2PARAM_new, +PKCS12_BAGS_free, +PKCS12_BAGS_new, +PKCS12_MAC_DATA_free, +PKCS12_MAC_DATA_new, +PKCS12_SAFEBAG_free, +PKCS12_SAFEBAG_new, +PKCS12_free, +PKCS12_new, +PKCS7_DIGEST_free, +PKCS7_DIGEST_new, +PKCS7_ENCRYPT_free, +PKCS7_ENCRYPT_new, +PKCS7_ENC_CONTENT_free, +PKCS7_ENC_CONTENT_new, +PKCS7_ENVELOPE_free, +PKCS7_ENVELOPE_new, +PKCS7_ISSUER_AND_SERIAL_free, +PKCS7_ISSUER_AND_SERIAL_new, +PKCS7_RECIP_INFO_free, +PKCS7_RECIP_INFO_new, +PKCS7_SIGNED_free, +PKCS7_SIGNED_new, +PKCS7_SIGNER_INFO_free, +PKCS7_SIGNER_INFO_new, +PKCS7_SIGN_ENVELOPE_free, +PKCS7_SIGN_ENVELOPE_new, +PKCS7_dup, +PKCS7_free, +PKCS7_new, +PKCS7_print_ctx, +PKCS8_PRIV_KEY_INFO_free, +PKCS8_PRIV_KEY_INFO_new, +PKEY_USAGE_PERIOD_free, +PKEY_USAGE_PERIOD_new, +POLICYINFO_free, +POLICYINFO_new, +POLICYQUALINFO_free, +POLICYQUALINFO_new, +POLICY_CONSTRAINTS_free, +POLICY_CONSTRAINTS_new, +POLICY_MAPPING_free, +POLICY_MAPPING_new, +PROXY_CERT_INFO_EXTENSION_free, +PROXY_CERT_INFO_EXTENSION_new, +PROXY_POLICY_free, +PROXY_POLICY_new, +RSAPrivateKey_dup, +RSAPublicKey_dup, +RSA_OAEP_PARAMS_free, +RSA_OAEP_PARAMS_new, +RSA_PSS_PARAMS_free, +RSA_PSS_PARAMS_new, +SCT_LIST_free, +SXNETID_free, +SXNETID_new, +SXNET_free, +SXNET_new, +TLS_FEATURE_free, +TLS_FEATURE_new, +TS_ACCURACY_dup, +TS_ACCURACY_free, +TS_ACCURACY_new, +TS_MSG_IMPRINT_dup, +TS_MSG_IMPRINT_free, +TS_MSG_IMPRINT_new, +TS_REQ_dup, +TS_REQ_free, +TS_REQ_new, +TS_RESP_dup, +TS_RESP_free, +TS_RESP_new, +TS_STATUS_INFO_dup, +TS_STATUS_INFO_free, +TS_STATUS_INFO_new, +TS_TST_INFO_dup, +TS_TST_INFO_free, +TS_TST_INFO_new, +USERNOTICE_free, +USERNOTICE_new, +X509_ALGOR_free, +X509_ALGOR_new, +X509_ATTRIBUTE_dup, +X509_ATTRIBUTE_free, +X509_ATTRIBUTE_new, +X509_CERT_AUX_free, +X509_CERT_AUX_new, +X509_CINF_free, +X509_CINF_new, +X509_CRL_INFO_free, +X509_CRL_INFO_new, +X509_CRL_dup, +X509_CRL_free, +X509_CRL_new, +X509_EXTENSION_dup, +X509_EXTENSION_free, +X509_EXTENSION_new, +X509_NAME_ENTRY_dup, +X509_NAME_ENTRY_free, +X509_NAME_ENTRY_new, +X509_NAME_dup, +X509_NAME_free, +X509_NAME_new, +X509_REQ_INFO_free, +X509_REQ_INFO_new, +X509_REQ_dup, +X509_REQ_free, +X509_REQ_new, +X509_REVOKED_dup, +X509_REVOKED_free, +X509_REVOKED_new, +X509_SIG_free, +X509_SIG_new, +X509_VAL_free, +X509_VAL_new, +X509_dup, +- ASN1 object utilities + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/asn1t.h> + + DECLARE_ASN1_FUNCTIONS(type) + IMPLEMENT_ASN1_FUNCTIONS(stname) + + typedef struct ASN1_ITEM_st ASN1_ITEM; + + extern const ASN1_ITEM TYPE_it; + TYPE *TYPE_new(void); + TYPE *TYPE_dup(TYPE *a); + void TYPE_free(TYPE *a); + int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx); + +=head1 DESCRIPTION + +In the description below, I<TYPE> is used +as a placeholder for any of the OpenSSL datatypes, such as I<X509>. + +The OpenSSL ASN1 parsing library templates are like a data-driven bytecode +interpreter. +Every ASN1 object as a global variable, TYPE_it, that describes the item +such as its fields. (On systems which cannot export variables from shared +libraries, the global is instead a function which returns a pointer to a +static variable. + +The macro DECLARE_ASN1_FUNCTIONS() is typically used in header files +to generate the function declarations. + +The macro IMPLEMENT_ASN1_FUNCTIONS() is used once in a source file +to generate the function bodies. + + +TYPE_new() allocates an empty object of the indicated type. +The object returned must be released by calling TYPE_free(). + +TYPE_dup() copies an existing object. + +TYPE_free() releases the object and all pointers and sub-objects +within it. + +TYPE_print_ctx() prints the object B<a> on the specified BIO B<out>. +Each line will be prefixed with B<indent> spaces. +The B<pctx> specifies the printing context and is for internal +use; use NULL to get the default behavior. If a print function is +user-defined, then pass in any B<pctx> down to any nested calls. + +=head1 RETURN VALUES + +TYPE_new() and TYPE_dup() return a pointer to the object or NULL on failure. + +TYPE_print_ctx() returns 1 on success or zero on failure. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_get0_notBefore.pod b/openssl-1.1.0h/doc/crypto/X509_get0_notBefore.pod new file mode 100644 index 0000000..0427d41 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_get0_notBefore.pod @@ -0,0 +1,103 @@ +=pod + +=head1 NAME + +X509_get0_notBefore, X509_getm_notBefore, X509_get0_notAfter, +X509_getm_notAfter, X509_set1_notBefore, X509_set1_notAfter, +X509_CRL_get0_lastUpdate, X509_CRL_get0_nextUpdate, X509_CRL_set1_lastUpdate, +X509_CRL_set1_nextUpdate - get or set certificate or CRL dates + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + const ASN1_TIME *X509_get0_notBefore(const X509 *x); + const ASN1_TIME *X509_get0_notAfter(const X509 *x); + + ASN1_TIME *X509_getm_notBefore(const X509 *x); + ASN1_TIME *X509_getm_notAfter(const X509 *x); + + int X509_set1_notBefore(X509 *x, const ASN1_TIME *tm); + int X509_set1_notAfter(X509 *x, const ASN1_TIME *tm); + + const ASN1_TIME *X509_CRL_get0_lastUpdate(const X509_CRL *crl); + const ASN1_TIME *X509_CRL_get0_nextUpdate(const X509_CRL *crl); + + int X509_CRL_set1_lastUpdate(X509_CRL *x, const ASN1_TIME *tm); + int X509_CRL_set1_nextUpdate(X509_CRL *x, const ASN1_TIME *tm); + +=head1 DESCRIPTION + +X509_get0_notBefore() and X509_get0_notAfter() return the B<notBefore> +and B<notAfter> fields of certificate B<x> respectively. The value +returned is an internal pointer which must not be freed up after +the call. + +X509_getm_notBefore() and X509_getm_notAfter() are similar to +X509_get0_notBefore() and X509_get0_notAfter() except they return +non-constant mutable references to the associated date field of +the certificate. + +X509_set1_notBefore() and X509_set1_notAfter() set the B<notBefore> +and B<notAfter> fields of B<x> to B<tm>. Ownership of the passed +parameter B<tm> is not transferred by these functions so it must +be freed up after the call. + +X509_CRL_get0_lastUpdate() and X509_CRL_get0_nextUpdate() return the +B<lastUpdate> and B<nextUpdate> fields of B<crl>. The value +returned is an internal pointer which must not be freed up after +the call. If the B<nextUpdate> field is absent from B<crl> then +B<NULL> is returned. + +X509_CRL_set1_lastUpdate() and X509_CRL_set1_nextUpdate() set the B<lastUpdate> +and B<nextUpdate> fields of B<crl> to B<tm>. Ownership of the passed parameter +B<tm> is not transferred by these functions so it must be freed up after the +call. + +=head1 RETURN VALUES + +X509_get0_notBefore(), X509_get0_notAfter() and X509_CRL_get0_lastUpdate() +return a pointer to an B<ASN1_TIME> structure. + +X509_CRL_get0_lastUpdate() return a pointer to an B<ASN1_TIME> structure +or NULL if the B<lastUpdate> field is absent. + +X509_set1_notBefore(), X509_set1_notAfter(), X509_CRL_set1_lastUpdate() and +X509_CRL_set1_nextUpdate() return 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +These functions are available in all versions of OpenSSL. + +X509_get_notBefore() and X509_get_notAfter() were deprecated in OpenSSL +1.1.0 + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_get0_signature.pod b/openssl-1.1.0h/doc/crypto/X509_get0_signature.pod new file mode 100644 index 0000000..61a2dda --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_get0_signature.pod @@ -0,0 +1,97 @@ +=pod + +=head1 NAME + +X509_get0_signature, X509_get_signature_nid, X509_get0_tbs_sigalg, +X509_REQ_get0_signature, X509_REQ_get_signature_nid, X509_CRL_get0_signature, +X509_CRL_get_signature_nid - signature information + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + void X509_get0_signature(const ASN1_BIT_STRING **psig, + const X509_ALGOR **palg, + const X509 *x); + int X509_get_signature_nid(const X509 *x); + const X509_ALGOR *X509_get0_tbs_sigalg(const X509 *x); + + void X509_REQ_get0_signature(const X509_REQ *crl, + const ASN1_BIT_STRING **psig, + const X509_ALGOR **palg); + int X509_REQ_get_signature_nid(const X509_REQ *crl); + + void X509_CRL_get0_signature(const X509_CRL *crl, + const ASN1_BIT_STRING **psig, + const X509_ALGOR **palg); + int X509_CRL_get_signature_nid(const X509_CRL *crl); + +=head1 DESCRIPTION + +X509_get0_signature() sets B<*psig> to the signature of B<x> and B<*palg> +to the signature algorithm of B<x>. The values returned are internal +pointers which B<MUST NOT> be freed up after the call. + +X509_get0_tbs_sigalg() returns the signature algorithm in the signed +portion of B<x>. + +X509_get_signature_nid() returns the NID corresponding to the signature +algorithm of B<x>. + +X509_REQ_get0_signature(), X509_REQ_get_signature_nid() +X509_CRL_get0_signature() and X509_CRL_get_signature_nid() perform the +same function for certificate requests and CRLs. + +=head1 NOTES + +These functions provide lower level access to signatures in certificates +where an application wishes to analyse or generate a signature in a form +where X509_sign() et al is not appropriate (for example a non standard +or unsupported format). + +=head1 RETURN VALUES + +X509_get_signature_nid(), X509_REQ_get_signature_nid() and +X509_CRL_get_signature_nid() return a NID. + +X509_get0_signature(), X509_REQ_get0_signature() and +X509_CRL_get0_signature() do not return values. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +X509_get0_signature() and X509_get_signature_nid() were first added to +OpenSSL 1.0.2. + +X509_REQ_get0_signature(), X509_REQ_get_signature_nid(), +X509_CRL_get0_signature() and X509_CRL_get_signature_nid() were first added +to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_get0_uids.pod b/openssl-1.1.0h/doc/crypto/X509_get0_uids.pod new file mode 100644 index 0000000..4eab26e --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_get0_uids.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +X509_get0_uids - get certificate unique identifiers + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + void X509_get0_uids(const X509 *x, const ASN1_BIT_STRING **piuid, + const ASN1_BIT_STRING **psuid); + +=head1 DESCRIPTION + +X509_get0_uids() sets B<*piuid> and B<*psuid> to the issuer and subject unique +identifiers of certificate B<x> or NULL if the fields are not present. + +=head1 NOTES + +The issuer and subject unique identifier fields are very rarely encountered in +practice outside test cases. + +=head1 RETURN VALUES + +X509_get0_uids() does not return a value. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_get_extension_flags.pod b/openssl-1.1.0h/doc/crypto/X509_get_extension_flags.pod new file mode 100644 index 0000000..c07ef97 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_get_extension_flags.pod @@ -0,0 +1,181 @@ +=pod + +=head1 NAME + +X509_get0_subject_key_id, +X509_get0_authority_key_id, +X509_get_pathlen, +X509_get_extension_flags, +X509_get_key_usage, +X509_get_extended_key_usage, +X509_set_proxy_flag, +X509_set_proxy_pathlen, +X509_get_proxy_pathlen - retrieve certificate extension data + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + long X509_get_pathlen(X509 *x); + uint32_t X509_get_extension_flags(X509 *x); + uint32_t X509_get_key_usage(X509 *x); + uint32_t X509_get_extended_key_usage(X509 *x); + const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x); + const ASN1_OCTET_STRING *X509_get0_authority_key_id(X509 *x); + void X509_set_proxy_flag(X509 *x); + void X509_set_proxy_pathlen(int l); + long X509_get_proxy_pathlen(X509 *x); + +=head1 DESCRIPTION + +These functions retrieve information related to commonly used certificate extensions. + +X509_get_pathlen() retrieves the path length extension from a certificate. +This extension is used to limit the length of a cert chain that may be +issued from that CA. + +X509_get_extension_flags() retrieves general information about a certificate, +it will return one or more of the following flags ored together. + +=over 4 + +=item B<EXFLAG_V1> + +The certificate is an obsolete version 1 certificate. + +=item B<EXFLAG_BCONS> + +The certificate contains a basic constraints extension. + +=item B<EXFLAG_CA> + +The certificate contains basic constraints and asserts the CA flag. + +=item B<EXFLAG_PROXY> + +The certificate is a valid proxy certificate. + +=item B<EXFLAG_SI> + +The certificate is self issued (that is subject and issuer names match). + +=item B<EXFLAG_SS> + +The subject and issuer names match and extension values imply it is self +signed. + +=item B<EXFLAG_FRESHEST> + +The freshest CRL extension is present in the certificate. + +=item B<EXFLAG_CRITICAL> + +The certificate contains an unhandled critical extension. + +=item B<EXFLAG_INVALID> + +Some certificate extension values are invalid or inconsistent. The +certificate should be rejected. + +=item B<EXFLAG_KUSAGE> + +The certificate contains a key usage extension. The value can be retrieved +using X509_get_key_usage(). + +=item B<EXFLAG_XKUSAGE> + +The certificate contains an extended key usage extension. The value can be +retrieved using X509_get_extended_key_usage(). + +=back + +X509_get_key_usage() returns the value of the key usage extension. If key +usage is present will return zero or more of the flags: +B<KU_DIGITAL_SIGNATURE>, B<KU_NON_REPUDIATION>, B<KU_KEY_ENCIPHERMENT>, +B<KU_DATA_ENCIPHERMENT>, B<KU_KEY_AGREEMENT>, B<KU_KEY_CERT_SIGN>, +B<KU_CRL_SIGN>, B<KU_ENCIPHER_ONLY> or B<KU_DECIPHER_ONLY> corresponding to +individual key usage bits. If key usage is absent then B<UINT32_MAX> is +returned. + +X509_get_extended_key_usage() returns the value of the extended key usage +extension. If extended key usage is present it will return zero or more of the +flags: B<XKU_SSL_SERVER>, B<XKU_SSL_CLIENT>, B<XKU_SMIME>, B<XKU_CODE_SIGN> +B<XKU_OCSP_SIGN>, B<XKU_TIMESTAMP>, B<XKU_DVCS> or B<XKU_ANYEKU>. These +correspond to the OIDs B<id-kp-serverAuth>, B<id-kp-clientAuth>, +B<id-kp-emailProtection>, B<id-kp-codeSigning>, B<id-kp-OCSPSigning>, +B<id-kp-timeStamping>, B<id-kp-dvcs> and B<anyExtendedKeyUsage> respectively. +Additionally B<XKU_SGC> is set if either Netscape or Microsoft SGC OIDs are +present. + +X509_get0_subject_key_id() returns an internal pointer to the subject key +identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension +is not present or cannot be parsed. + +X509_get0_authority_key_id() returns an internal pointer to the authority key +identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension +is not present or cannot be parsed. + +X509_set_proxy_flag() marks the certificate with the B<EXFLAG_PROXY> flag. +This is for the users who need to mark non-RFC3820 proxy certificates as +such, as OpenSSL only detects RFC3820 compliant ones. + +X509_set_proxy_pathlen() sets the proxy certificate path length for the given +certificate B<x>. This is for the users who need to mark non-RFC3820 proxy +certificates as such, as OpenSSL only detects RFC3820 compliant ones. + +X509_get_proxy_pathlen() returns the proxy certificate path length for the +given certificate B<x> if it is a proxy certificate. + +=head1 NOTES + +The value of the flags correspond to extension values which are cached +in the B<X509> structure. If the flags returned do not provide sufficient +information an application should examine extension values directly +for example using X509_get_ext_d2i(). + +If the key usage or extended key usage extension is absent then typically usage +is unrestricted. For this reason X509_get_key_usage() and +X509_get_extended_key_usage() return B<UINT32_MAX> when the corresponding +extension is absent. Applications can additionally check the return value of +X509_get_extension_flags() and take appropriate action is an extension is +absent. + +If X509_get0_subject_key_id() returns B<NULL> then the extension may be +absent or malformed. Applications can determine the precise reason using +X509_get_ext_d2i(). + +=head1 RETURN VALUE + +X509_get_pathlen() returns the path length value, or -1 if the extension +is not present. + +X509_get_extension_flags(), X509_get_key_usage() and +X509_get_extended_key_usage() return sets of flags corresponding to the +certificate extension values. + +X509_get0_subject_key_id() returns the subject key identifier as a +pointer to an B<ASN1_OCTET_STRING> structure or B<NULL> if the extension +is absent or an error occurred during parsing. + +X509_get_proxy_pathlen() returns the path length value if the given +certificate is a proxy one and has a path length set, and -1 otherwise. + +=head1 SEE ALSO + +L<X509_check_purpose(3)> + +=head1 HISTORY + +X509_get_pathlen(), X509_set_proxy_flag(), X509_set_proxy_pathlen() and +X509_get_proxy_pathlen() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_get_pubkey.pod b/openssl-1.1.0h/doc/crypto/X509_get_pubkey.pod new file mode 100644 index 0000000..2b9a956 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_get_pubkey.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +X509_get_pubkey, X509_get0_pubkey, X509_set_pubkey, X509_get_X509_PUBKEY, +X509_REQ_get_pubkey, X509_REQ_get0_pubkey, X509_REQ_set_pubkey, +X509_REQ_get_X509_PUBKEY - get or set certificate or certificate request +public key + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + EVP_PKEY *X509_get_pubkey(X509 *x); + EVP_PKEY *X509_get0_pubkey(const X509 *x); + int X509_set_pubkey(X509 *x, EVP_PKEY *pkey); + X509_PUBKEY *X509_get_X509_PUBKEY(X509 *x); + + EVP_PKEY *X509_REQ_get_pubkey(X509_REQ *req); + EVP_PKEY *X509_REQ_get0_pubkey(X509_REQ *req); + int X509_REQ_set_pubkey(X509_REQ *x, EVP_PKEY *pkey); + X509_PUBKEY *X509_REQ_get_X509_PUBKEY(X509_REQ *x); + +=head1 DESCRIPTION + +X509_get_pubkey() attempts to decode the public key for certificate B<x>. If +successful it returns the public key as an B<EVP_PKEY> pointer with its +reference count incremented: this means the returned key must be freed up +after use. X509_get0_pubkey() is similar except it does B<not> increment +the reference count of the returned B<EVP_PKEY> so it must not be freed up +after use. + +X509_get_X509_PUBKEY() returns an internal pointer to the B<X509_PUBKEY> +structure which encodes the certificate of B<x>. The returned value +must not be freed up after use. + +X509_set_pubkey() attempts to set the public key for certificate B<x> to +B<pkey>. The key B<pkey> should be freed up after use. + +X509_REQ_get_pubkey(), X509_REQ_get0_pubkey(), X509_REQ_set_pubkey() and +X509_REQ_get_X509_PUBKEY() are similar but operate on certificate request B<req>. + +=head1 NOTES + +The first time a public key is decoded the B<EVP_PKEY> structure is +cached in the certificate or certificate request itself. Subsequent calls +return the cached structure with its reference count incremented to +improve performance. + +=head1 RETURN VALUES + +X509_get_pubkey(), X509_get0_pubkey(), X509_get_X509_PUBKEY(), +X509_REQ_get_pubkey() and X509_REQ_get_X509_PUBKEY() return a public key or +B<NULL> if an error occurred. + +X509_set_pubkey() and X509_REQ_set_pubkey() return 1 for success and 0 +for failure. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_get_serialNumber.pod b/openssl-1.1.0h/doc/crypto/X509_get_serialNumber.pod new file mode 100644 index 0000000..2e81c62 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_get_serialNumber.pod @@ -0,0 +1,71 @@ +=pod + +=head1 NAME + +X509_get_serialNumber, +X509_get0_serialNumber, +X509_set_serialNumber +- get or set certificate serial number + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + ASN1_INTEGER *X509_get_serialNumber(X509 *x); + const ASN1_INTEGER *X509_get0_serialNumber(const X509 *x); + int X509_set_serialNumber(X509 *x, ASN1_INTEGER *serial); + +=head1 DESCRIPTION + +X509_get_serialNumber() returns the serial number of certificate B<x> as an +B<ASN1_INTEGER> structure which can be examined or initialised. The value +returned is an internal pointer which B<MUST NOT> be freed up after the call. + +X509_get0_serialNumber() is the same as X509_get_serialNumber() except it +accepts a const parameter and returns a const result. + +X509_set_serialNumber() sets the serial number of certificate B<x> to +B<serial>. A copy of the serial number is used internally so B<serial> should +be freed up after use. + +=head1 RETURN VALUES + +X509_get_serialNumber() and X509_get0_serialNumber() return an B<ASN1_INTEGER> +structure. + +X509_set_serialNumber() returns 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +X509_get_serialNumber() and X509_set_serialNumber() are available in +all versions of OpenSSL. X509_get0_serialNumber() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_get_subject_name.pod b/openssl-1.1.0h/doc/crypto/X509_get_subject_name.pod new file mode 100644 index 0000000..ce36bbf --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_get_subject_name.pod @@ -0,0 +1,86 @@ +=pod + +=head1 NAME + +X509_get_subject_name, X509_set_subject_name, X509_get_issuer_name, +X509_set_issuer_name, X509_REQ_get_subject_name, X509_REQ_set_subject_name, +X509_CRL_get_issuer, X509_CRL_set_issuer_name - get and set issuer or +subject names + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509_NAME *X509_get_subject_name(const X509 *x); + int X509_set_subject_name(X509 *x, X509_NAME *name); + + X509_NAME *X509_get_issuer_name(const X509 *x); + int X509_set_issuer_name(X509 *x, X509_NAME *name); + + X509_NAME *X509_REQ_get_subject_name(const X509_REQ *req); + int X509_REQ_set_subject_name(X509_REQ *req, X509_NAME *name); + + X509_NAME *X509_CRL_get_issuer(const X509_CRL *crl); + int X509_CRL_set_issuer_name(X509_CRL *x, X509_NAME *name); + +=head1 DESCRIPTION + +X509_get_subject_name() returns the subject name of certificate B<x>. The +returned value is an internal pointer which B<MUST NOT> be freed. + +X509_set_subject_name() sets the issuer name of certificate B<x> to +B<name>. The B<name> parameter is copied internally and should be freed +up when it is no longer needed. + +X509_get_issuer_name() and X509_set_issuer_name() are identical to +X509_get_subject_name() and X509_set_subject_name() except the get and +set the issuer name of B<x>. + +Similarly X509_REQ_get_subject_name(), X509_REQ_set_subject_name(), + X509_CRL_get_issuer() and X509_CRL_set_issuer_name() get or set the subject +or issuer names of certificate requests of CRLs respectively. + +=head1 RETURN VALUES + +X509_get_subject_name(), X509_get_issuer_name(), X509_REQ_get_subject_name() +and X509_CRL_get_issuer() return an B<X509_NAME> pointer. + +X509_set_subject_name(), X509_set_issuer_name(), X509_REQ_set_subject_name() +and X509_CRL_set_issuer_name() return 1 for success and 0 for failure. + +=head1 HISTORY + +X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in +earlier versions. + +X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was first added +to OpenSSL 1.0.0 as a macro. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, L<d2i_X509(3)> +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_get_version.pod b/openssl-1.1.0h/doc/crypto/X509_get_version.pod new file mode 100644 index 0000000..c1826ea --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_get_version.pod @@ -0,0 +1,83 @@ +=pod + +=head1 NAME + +X509_get_version, X509_set_version, X509_REQ_get_version, X509_REQ_set_version, +X509_CRL_get_version, X509_CRL_set_version - get or set certificate, +certificate request or CRL version + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + long X509_get_version(const X509 *x); + int X509_set_version(X509 *x, long version); + + long X509_REQ_get_version(const X509_REQ *req); + int X509_REQ_set_version(X509_REQ *x, long version); + + long X509_CRL_get_version(const X509_CRL *crl); + int X509_CRL_set_version(X509_CRL *x, long version); + +=head1 DESCRIPTION + +X509_get_version() returns the numerical value of the version field of +certificate B<x>. Note: this is defined by standards (X.509 et al) to be one +less than the certificate version. So a version 3 certificate will return 2 and +a version 1 certificate will return 0. + +X509_set_version() sets the numerical value of the version field of certificate +B<x> to B<version>. + +Similarly X509_REQ_get_version(), X509_REQ_set_version(), +X509_CRL_get_version() and X509_CRL_set_version() get and set the version +number of certificate requests and CRLs. + +=head1 NOTES + +The version field of certificates, certificate requests and CRLs has a +DEFAULT value of B<v1(0)> meaning the field should be omitted for version +1. This is handled transparently by these functions. + +=head1 RETURN VALUES + +X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version() +return the numerical value of the version field. + +X509_set_version(), X509_REQ_set_version() and X509_CRL_set_version() +return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version() are +functions in OpenSSL 1.1.0, in previous versions they were macros. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_new.pod b/openssl-1.1.0h/doc/crypto/X509_new.pod new file mode 100644 index 0000000..4f53499 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_new.pod @@ -0,0 +1,83 @@ +=pod + +=head1 NAME + +X509_chain_up_ref, +X509_new, X509_free, X509_up_ref - X509 certificate ASN1 allocation functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509 *X509_new(void); + void X509_free(X509 *a); + int X509_up_ref(X509 *a); + STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x); + +=head1 DESCRIPTION + +The X509 ASN1 allocation routines, allocate and free an +X509 structure, which represents an X509 certificate. + +X509_new() allocates and initializes a X509 structure with reference count +B<1>. + +X509_free() decrements the reference count of B<X509> structure B<a> and +frees it up if the reference count is zero. If B<a> is NULL nothing is done. + +X509_up_ref() increments the reference count of B<a>. + +X509_chain_up_ref() increases the reference count of all certificates in +chain B<x> and returns a copy of the stack. + +=head1 NOTES + +The function X509_up_ref() if useful if a certificate structure is being +used by several different operations each of which will free it up after +use: this avoids the need to duplicate the entire certificate structure. + +The function X509_chain_up_ref() doesn't just up the reference count of +each certificate it also returns a copy of the stack, using sk_X509_dup(), +but it serves a similar purpose: the returned chain persists after the +original has been freed. + +=head1 RETURN VALUES + +If the allocation fails, X509_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)>. +Otherwise it returns a pointer to the newly allocated structure. + +X509_up_ref() returns 1 for success and 0 for failure. + +X509_chain_up_ref() returns a copy of the stack or B<NULL> if an error +occurred. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_sign.pod b/openssl-1.1.0h/doc/crypto/X509_sign.pod new file mode 100644 index 0000000..994fd43 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_sign.pod @@ -0,0 +1,99 @@ +=pod + +=head1 NAME + +X509_sign, X509_sign_ctx, X509_verify, X509_REQ_sign, X509_REQ_sign_ctx, +X509_REQ_verify, X509_CRL_sign, X509_CRL_sign_ctx, X509_CRL_verify - +sign or verify certificate, certificate request or CRL signature + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_sign(X509 *x, EVP_PKEY *pkey, const EVP_MD *md); + int X509_sign_ctx(X509 *x, EVP_MD_CTX *ctx); + int X509_verify(X509 *a, EVP_PKEY *r); + + int X509_REQ_sign(X509_REQ *x, EVP_PKEY *pkey, const EVP_MD *md); + int X509_REQ_sign_ctx(X509_REQ *x, EVP_MD_CTX *ctx); + int X509_REQ_verify(X509_REQ *a, EVP_PKEY *r); + + int X509_CRL_sign(X509_CRL *x, EVP_PKEY *pkey, const EVP_MD *md); + int X509_CRL_sign_ctx(X509_CRL *x, EVP_MD_CTX *ctx); + int X509_CRL_verify(X509_CRL *a, EVP_PKEY *r); + +=head1 DESCRIPTION + +X509_sign() signs certificate B<x> using private key B<pkey> and message +digest B<md> and sets the signature in B<x>. X509_sign_ctx() also signs +certificate B<x> but uses the parameters contained in digest context B<ctx>. + +X509_verify() verifies the signature of certificate B<x> using public key +B<pkey>. Only the signature is checked: no other checks (such as certificate +chain validity) are performed. + +X509_REQ_sign(), X509_REQ_sign_ctx(), X509_REQ_verify(), +X509_CRL_sign(), X509_CRL_sign_ctx() and X509_CRL_verify() sign and verify +certificate requests and CRLs respectively. + +=head1 NOTES + +X509_sign_ctx() is used where the default parameters for the corresponding +public key and digest are not suitable. It can be used to sign keys using +RSA-PSS for example. + +For efficiency reasons and to work around ASN.1 encoding issues the encoding +of the signed portion of a certificate, certificate request and CRL is cached +internally. If the signed portion of the structure is modified the encoding +is not always updated meaning a stale version is sometimes used. This is not +normally a problem because modifying the signed portion will invalidate the +signature and signing will always update the encoding. + +=head1 RETURN VALUES + +X509_sign(), X509_sign_ctx(), X509_REQ_sign(), X509_REQ_sign_ctx(), +X509_CRL_sign() and X509_CRL_sign_ctx() return the size of the signature +in bytes for success and zero for failure. + +X509_verify(), X509_REQ_verify() and X509_CRL_verify() return 1 if the +signature is valid and 0 if the signature check fails. If the signature +could not be checked at all because it was invalid or some other error +occurred then -1 is returned. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +X509_sign(), X509_REQ_sign() and X509_CRL_sign() are available in all +versions of OpenSSL. + +X509_sign_ctx(), X509_REQ_sign_ctx() and X509_CRL_sign_ctx() were first added +to OpenSSL 1.0.1. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509_verify_cert.pod b/openssl-1.1.0h/doc/crypto/X509_verify_cert.pod new file mode 100644 index 0000000..74acf8d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_verify_cert.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + +X509_verify_cert - discover and verify X509 certificate chain + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_verify_cert(X509_STORE_CTX *ctx); + +=head1 DESCRIPTION + +The X509_verify_cert() function attempts to discover and validate a +certificate chain based on parameters in B<ctx>. A complete description of +the process is contained in the L<verify(1)> manual page. + +=head1 RETURN VALUES + +If a complete chain can be built and validated this function returns 1, +otherwise it return zero, in exceptional circumstances it can also +return a negative code. + +If the function fails additional error information can be obtained by +examining B<ctx> using, for example X509_STORE_CTX_get_error(). + +=head1 NOTES + +Applications rarely call this function directly but it is used by +OpenSSL internally for certificate validation, in both the S/MIME and +SSL/TLS code. + +A negative return value from X509_verify_cert() can occur if it is invoked +incorrectly, such as with no certificate set in B<ctx>, or when it is called +twice in succession without reinitialising B<ctx> for the second call. +A negative return value can also happen due to internal resource problems or if +a retry operation is requested during internal lookups (which never happens +with standard lookup methods). +Applications must check for <= 0 return value on error. + +=head1 BUGS + +This function uses the header B<x509.h> as opposed to most chain verification +functions which use B<x509_vfy.h>. + +=head1 SEE ALSO + +L<X509_STORE_CTX_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/X509v3_get_ext_by_NID.pod b/openssl-1.1.0h/doc/crypto/X509v3_get_ext_by_NID.pod new file mode 100644 index 0000000..032f71c --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509v3_get_ext_by_NID.pod @@ -0,0 +1,140 @@ +=pod + +=head1 NAME + +X509v3_get_ext_count, X509v3_get_ext, X509v3_get_ext_by_NID, +X509v3_get_ext_by_OBJ, X509v3_get_ext_by_critical, X509v3_delete_ext, +X509v3_add_ext, X509_get_ext_count, X509_get_ext, +X509_get_ext_by_NID, X509_get_ext_by_OBJ, X509_get_ext_by_critical, +X509_delete_ext, X509_add_ext, X509_CRL_get_ext_count, X509_CRL_get_ext, +X509_CRL_get_ext_by_NID, X509_CRL_get_ext_by_OBJ, X509_CRL_get_ext_by_critical, +X509_CRL_delete_ext, X509_CRL_add_ext, X509_REVOKED_get_ext_count, +X509_REVOKED_get_ext, X509_REVOKED_get_ext_by_NID, X509_REVOKED_get_ext_by_OBJ, +X509_REVOKED_get_ext_by_critical, X509_REVOKED_delete_ext, +X509_REVOKED_add_ext - extension stack utility functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x); + X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc); + + int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x, + int nid, int lastpos); + int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x, + const ASN1_OBJECT *obj, int lastpos); + int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x, + int crit, int lastpos); + X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc); + STACK_OF(X509_EXTENSION) *X509v3_add_ext(STACK_OF(X509_EXTENSION) **x, + X509_EXTENSION *ex, int loc); + + int X509_get_ext_count(const X509 *x); + X509_EXTENSION *X509_get_ext(const X509 *x, int loc); + int X509_get_ext_by_NID(const X509 *x, int nid, int lastpos); + int X509_get_ext_by_OBJ(const X509 *x, const ASN1_OBJECT *obj, int lastpos); + int X509_get_ext_by_critical(const X509 *x, int crit, int lastpos); + X509_EXTENSION *X509_delete_ext(X509 *x, int loc); + int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc); + + int X509_CRL_get_ext_count(const X509_CRL *x); + X509_EXTENSION *X509_CRL_get_ext(const X509_CRL *x, int loc); + int X509_CRL_get_ext_by_NID(const X509_CRL *x, int nid, int lastpos); + int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, int lastpos); + int X509_CRL_get_ext_by_critical(const X509_CRL *x, int crit, int lastpos); + X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc); + int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc); + + int X509_REVOKED_get_ext_count(const X509_REVOKED *x); + X509_EXTENSION *X509_REVOKED_get_ext(const X509_REVOKED *x, int loc); + int X509_REVOKED_get_ext_by_NID(const X509_REVOKED *x, int nid, int lastpos); + int X509_REVOKED_get_ext_by_OBJ(const X509_REVOKED *x, const ASN1_OBJECT *obj, + int lastpos); + int X509_REVOKED_get_ext_by_critical(const X509_REVOKED *x, int crit, int lastpos); + X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc); + int X509_REVOKED_add_ext(X509_REVOKED *x, X509_EXTENSION *ex, int loc); + +=head1 DESCRIPTION + +X509v3_get_ext_count() retrieves the number of extensions in B<x>. + +X509v3_get_ext() retrieves extension B<loc> from B<x>. The index B<loc> +can take any value from B<0> to X509_get_ext_count(x) - 1. The returned +extension is an internal pointer which B<must not> be freed up by the +application. + +X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension +with B<nid> or B<obj> from extension stack B<x>. The search starts from the +extension after B<lastpos> or from the beginning if <lastpos> is B<-1>. If +the extension is found its index is returned otherwise B<-1> is returned. + +X509v3_get_ext_by_critical() is similar to X509v3_get_ext_by_NID() except it +looks for an extension of criticality B<crit>. A zero value for B<crit> +looks for a non-critical extension a non-zero value looks for a critical +extension. + +X509v3_delete_ext() deletes the extension with index B<loc> from B<x>. The +deleted extension is returned and must be freed by the caller. If B<loc> +is in invalid index value B<NULL> is returned. + +X509v3_add_ext() adds extension B<ex> to stack B<*x> at position B<loc>. If +B<loc> is B<-1> the new extension is added to the end. If B<*x> is B<NULL> +a new stack will be allocated. The passed extension B<ex> is duplicated +internally so it must be freed after use. + +X509_get_ext_count(), X509_get_ext(), X509_get_ext_by_NID(), +X509_get_ext_by_OBJ(), X509_get_ext_by_critical(), X509_delete_ext() +and X509_add_ext() operate on the extensions of certificate B<x> they are +otherwise identical to the X509v3 functions. + +X509_CRL_get_ext_count(), X509_CRL_get_ext(), X509_CRL_get_ext_by_NID(), +X509_CRL_get_ext_by_OBJ(), X509_CRL_get_ext_by_critical(), +X509_CRL_delete_ext() and X509_CRL_add_ext() operate on the extensions of +CRL B<x> they are otherwise identical to the X509v3 functions. + +X509_REVOKED_get_ext_count(), X509_REVOKED_get_ext(), +X509_REVOKED_get_ext_by_NID(), X509_REVOKED_get_ext_by_OBJ(), +X509_REVOKED_get_ext_by_critical(), X509_REVOKED_delete_ext() and +X509_REVOKED_add_ext() operate on the extensions of CRL entry B<x> +they are otherwise identical to the X509v3 functions. + +=head1 NOTES + +These functions are used to examine stacks of extensions directly. Many +applications will want to parse or encode and add an extension: they should +use the extension encode and decode functions instead such as +X509_add1_ext_i2d() and X509_get_ext_d2i(). + +Extension indices start from zero, so a zero index return value is B<not> an +error. These search functions start from the extension B<after> the B<lastpos> +parameter so it should initially be set to B<-1>, if it is set to zero the +initial extension will not be checked. + +=head1 RETURN VALUES + +X509v3_get_ext_count() returns the extension count. + +X509v3_get_ext() and X509v3_delete_ext() return an B<X509_EXTENSION> pointer +or B<NULL> if an error occurs. + +X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and +X509v3_get_ext_by_critical() return the an extension index or B<-1> if an +error occurs. + +X509v3_add_ext() returns a stack of extensions or B<NULL> on error. + +=head1 SEE ALSO + +L<X509V3_get_d2i(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/bio.pod b/openssl-1.1.0h/doc/crypto/bio.pod new file mode 100644 index 0000000..1e1dd02 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/bio.pod @@ -0,0 +1,90 @@ +=pod + +=for comment openssl_manual_section 7 + +=head1 NAME + +bio - Basic I/O abstraction + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/bio.h> + +=head1 DESCRIPTION + +A BIO is an I/O abstraction, it hides many of the underlying I/O +details from an application. If an application uses a BIO for its +I/O it can transparently handle SSL connections, unencrypted network +connections and file I/O. + +There are two type of BIO, a source/sink BIO and a filter BIO. + +As its name implies a source/sink BIO is a source and/or sink of data, +examples include a socket BIO and a file BIO. + +A filter BIO takes data from one BIO and passes it through to +another, or the application. The data may be left unmodified (for +example a message digest BIO) or translated (for example an +encryption BIO). The effect of a filter BIO may change according +to the I/O operation it is performing: for example an encryption +BIO will encrypt data if it is being written to and decrypt data +if it is being read from. + +BIOs can be joined together to form a chain (a single BIO is a chain +with one component). A chain normally consist of one source/sink +BIO and one or more filter BIOs. Data read from or written to the +first BIO then traverses the chain to the end (normally a source/sink +BIO). + + +Some BIOs (such as memory BIOs) can be used immediately after calling +BIO_new(). Others (such as file BIOs) need some additional initialization, +and frequently a utility function exists to create and initialize such BIOs. + +If BIO_free() is called on a BIO chain it will only free one BIO resulting +in a memory leak. + +Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() +on it other than the discarded return value. + +Normally the B<type> argument is supplied by a function which returns a +pointer to a BIO_METHOD. There is a naming convention for such functions: +a source/sink BIO is normally called BIO_s_*() and a filter BIO +BIO_f_*(); + +=head1 EXAMPLE + +Create a memory BIO: + + BIO *mem = BIO_new(BIO_s_mem()); + +=head1 SEE ALSO + +L<BIO_ctrl(3)>, +L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>, +L<BIO_f_cipher(3)>, L<BIO_f_md(3)>, +L<BIO_f_null(3)>, L<BIO_f_ssl(3)>, +L<BIO_find_type(3)>, L<BIO_new(3)>, +L<BIO_new_bio_pair(3)>, +L<BIO_push(3)>, L<BIO_read(3)>, +L<BIO_s_accept(3)>, L<BIO_s_bio(3)>, +L<BIO_s_connect(3)>, L<BIO_s_fd(3)>, +L<BIO_s_file(3)>, L<BIO_s_mem(3)>, +L<BIO_s_mem(3)>, +L<BIO_s_null(3)>, L<BIO_s_socket(3)>, +L<BIO_set_callback(3)>, +L<BIO_should_retry(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut + diff --git a/openssl-1.1.0h/doc/crypto/crypto.pod b/openssl-1.1.0h/doc/crypto/crypto.pod new file mode 100644 index 0000000..082f843 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/crypto.pod @@ -0,0 +1,62 @@ +=pod + +=for comment openssl_manual_section:7 + +=head1 NAME + +crypto - OpenSSL cryptographic library + +=head1 SYNOPSIS + +See the individual manual pages for details. + +=head1 DESCRIPTION + +The OpenSSL B<crypto> library implements a wide range of cryptographic +algorithms used in various Internet standards. The services provided +by this library are used by the OpenSSL implementations of SSL, TLS +and S/MIME, and they have also been used to implement SSH, OpenPGP, and +other cryptographic standards. + +B<libcrypto> consists of a number of sub-libraries that implement the +individual algorithms. + +The functionality includes symmetric encryption, public key +cryptography and key agreement, certificate handling, cryptographic +hash functions, cryptographic pseudo-random number generator, and +various utilities. + +=head1 NOTES + +Some of the newer functions follow a naming convention using the numbers +B<0> and B<1>. For example the functions: + + int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); + int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); + +The B<0> version uses the supplied structure pointer directly +in the parent and it will be freed up when the parent is freed. +In the above example B<crl> would be freed but B<rev> would not. + +The B<1> function uses a copy of the supplied structure pointer +(or in some cases increases its link count) in the parent and +so both (B<x> and B<obj> above) should be freed up. + +=head1 RETURN VALUES + +See the individual manual pages for details. + +=head1 SEE ALSO + +L<openssl(1)>, L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/ct.pod b/openssl-1.1.0h/doc/crypto/ct.pod new file mode 100644 index 0000000..60718b3 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/ct.pod @@ -0,0 +1,55 @@ +=pod + +=for comment openssl_manual_section:7 + +=head1 NAME + +ct - Certificate Transparency + +=head1 SYNOPSIS + + #include <openssl/ct.h> + +=head1 DESCRIPTION + +This library implements Certificate Transparency (CT) verification for TLS +clients, as defined in RFC 6962. This verification can provide some confidence +that a certificate has been publicly logged in a set of CT logs. + +By default, these checks are disabled. They can be enabled using +SSL_CTX_ct_enable() or SSL_ct_enable(). + +This library can also be used to parse and examine CT data structures, such as +Signed Certificate Timestamps (SCTs), or to read a list of CT logs. There are +functions for: +- decoding and encoding SCTs in DER and TLS wire format. +- printing SCTs. +- verifying the authenticity of SCTs. +- loading a CT log list from a CONF file. + +=head1 SEE ALSO + +L<d2i_SCT_LIST(3)>, +L<CTLOG_STORE_new(3)>, +L<CTLOG_STORE_get0_log_by_id(3)>, +L<SCT_new(3)>, +L<SCT_print(3)>, +L<SCT_validate(3)>, +L<SCT_validate(3)>, +L<CT_POLICY_EVAL_CTX_new(3)>, +L<SSL_CTX_set_ct_validation_callback(3)> + +=head1 HISTORY + +This library was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/d2i_DHparams.pod b/openssl-1.1.0h/doc/crypto/d2i_DHparams.pod new file mode 100644 index 0000000..cd1c162 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/d2i_DHparams.pod @@ -0,0 +1,35 @@ +=pod + +=head1 NAME + +d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + DH *d2i_DHparams(DH **a, unsigned char **pp, long length); + int i2d_DHparams(DH *a, unsigned char **pp); + +=head1 DESCRIPTION + +These functions decode and encode PKCS#3 DH parameters using the +DHparameter structure described in PKCS#3. + +Otherwise these behave in a similar way to d2i_X509() and i2d_X509() +described in the L<d2i_X509(3)> manual page. + +=head1 SEE ALSO + +L<d2i_X509(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/d2i_Netscape_RSA.pod b/openssl-1.1.0h/doc/crypto/d2i_Netscape_RSA.pod new file mode 100644 index 0000000..ee39bd8 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/d2i_Netscape_RSA.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +i2d_Netscape_RSA, +d2i_Netscape_RSA +- insecure RSA public and private key encoding functions + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); + RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)()); + +=head1 DESCRIPTION + +These functions decode and encode an RSA private +key in NET format. These functions are present to provide compatibility +with very old software. This format has some severe security weaknesses +and should be avoided if possible. + +These functions are similar to the B<d2i_RSAPrivateKey> functions. + +=head1 SEE ALSO + +L<d2i_RSAPrivateKey(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/d2i_PKCS8PrivateKey_bio.pod b/openssl-1.1.0h/doc/crypto/d2i_PKCS8PrivateKey_bio.pod new file mode 100644 index 0000000..164d93f --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/d2i_PKCS8PrivateKey_bio.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +d2i_PKCS8PrivateKey_bio, d2i_PKCS8PrivateKey_fp, +i2d_PKCS8PrivateKey_bio, i2d_PKCS8PrivateKey_fp, +i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp - PKCS#8 format private key functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u); + EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u); + + int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid, + char *kstr, int klen, + pem_password_cb *cb, void *u); + +=head1 DESCRIPTION + +The PKCS#8 functions encode and decode private keys in PKCS#8 format using both +PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms. + +Other than the use of DER as opposed to PEM these functions are identical to the +corresponding B<PEM> function as described in L<PEM_read_PrivateKey(3)>. + +=head1 NOTES + +These functions are currently the only way to store encrypted private keys using DER format. + +Currently all the functions use BIOs or FILE pointers, there are no functions which +work directly on memory: this can be readily worked around by converting the buffers +to memory BIOs, see L<BIO_s_mem(3)> for details. + +=head1 SEE ALSO + +L<PEM_read_PrivateKey(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/d2i_PrivateKey.pod b/openssl-1.1.0h/doc/crypto/d2i_PrivateKey.pod new file mode 100644 index 0000000..f5b4667 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/d2i_PrivateKey.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +d2i_PrivateKey, d2i_PublicKey, d2i_AutoPrivateKey, +i2d_PrivateKey, i2d_PublicKey, +d2i_PrivateKey_bio, d2i_PrivateKey_fp +- decode and encode functions for reading and saving EVP_PKEY structures + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp, + long length); + EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **a, const unsigned char **pp, + long length); + EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp, + long length); + int i2d_PrivateKey(EVP_PKEY *a, unsigned char **pp); + int i2d_PublicKey(EVP_PKEY *a, unsigned char **pp); + + EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a); + EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a) + +=head1 DESCRIPTION + +d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to +use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The +B<type> parameter should be a public key algorithm constant such as +B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match B<type>. +d2i_PublicKey() does the same for public keys. + +d2i_AutoPrivateKey() is similar to d2i_PrivateKey() except it attempts to +automatically detect the private key format. + +i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is +defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format. +i2d_PublicKey() does the same for public keys. + +These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>. + +=head1 NOTES + +All these functions use DER format and unencrypted keys. Applications wishing +to encrypt or decrypt private keys should use other functions such as +d2i_PKC8PrivateKey() instead. + +If the B<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey() +(i.e. an existing structure is being reused) and the key format is PKCS#8 +then B<*a> will be freed and replaced on a successful call. + +=head1 RETURN VALUES + +d2i_PrivateKey() and d2i_AutoPrivateKey() return a valid B<EVP_KEY> structure +or B<NULL> if an error occurs. The error code can be obtained by calling +L<ERR_get_error(3)>. + +i2d_PrivateKey() returns the number of bytes successfully encoded or a +negative value if an error occurs. The error code can be obtained by calling +L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<crypto(7)>, +L<d2i_PKCS8PrivateKey_bio(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/d2i_X509.pod b/openssl-1.1.0h/doc/crypto/d2i_X509.pod new file mode 100644 index 0000000..1fbe5ca --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/d2i_X509.pod @@ -0,0 +1,601 @@ +=pod + +=head1 NAME + +d2i_ACCESS_DESCRIPTION, +d2i_ASIdOrRange, +d2i_ASIdentifierChoice, +d2i_ASIdentifiers, +d2i_ASN1_BIT_STRING, +d2i_ASN1_BMPSTRING, +d2i_ASN1_ENUMERATED, +d2i_ASN1_GENERALIZEDTIME, +d2i_ASN1_GENERALSTRING, +d2i_ASN1_IA5STRING, +d2i_ASN1_INTEGER, +d2i_ASN1_NULL, +d2i_ASN1_OBJECT, +d2i_ASN1_OCTET_STRING, +d2i_ASN1_PRINTABLE, +d2i_ASN1_PRINTABLESTRING, +d2i_ASN1_SEQUENCE_ANY, +d2i_ASN1_SET_ANY, +d2i_ASN1_T61STRING, +d2i_ASN1_TIME, +d2i_ASN1_TYPE, +d2i_ASN1_UINTEGER, +d2i_ASN1_UNIVERSALSTRING, +d2i_ASN1_UTCTIME, +d2i_ASN1_UTF8STRING, +d2i_ASN1_VISIBLESTRING, +d2i_ASRange, +d2i_AUTHORITY_INFO_ACCESS, +d2i_AUTHORITY_KEYID, +d2i_BASIC_CONSTRAINTS, +d2i_CERTIFICATEPOLICIES, +d2i_CMS_ContentInfo, +d2i_CMS_ReceiptRequest, +d2i_CMS_bio, +d2i_CRL_DIST_POINTS, +d2i_DHxparams, +d2i_DIRECTORYSTRING, +d2i_DISPLAYTEXT, +d2i_DIST_POINT, +d2i_DIST_POINT_NAME, +d2i_DSAPrivateKey, +d2i_DSAPrivateKey_bio, +d2i_DSAPrivateKey_fp, +d2i_DSAPublicKey, +d2i_DSA_PUBKEY, +d2i_DSA_PUBKEY_bio, +d2i_DSA_PUBKEY_fp, +d2i_DSA_SIG, +d2i_DSAparams, +d2i_ECPKParameters, +d2i_ECParameters, +d2i_ECPrivateKey, +d2i_ECPrivateKey_bio, +d2i_ECPrivateKey_fp, +d2i_EC_PUBKEY, +d2i_EC_PUBKEY_bio, +d2i_EC_PUBKEY_fp, +d2i_EDIPARTYNAME, +d2i_ESS_CERT_ID, +d2i_ESS_ISSUER_SERIAL, +d2i_ESS_SIGNING_CERT, +d2i_EXTENDED_KEY_USAGE, +d2i_GENERAL_NAME, +d2i_GENERAL_NAMES, +d2i_IPAddressChoice, +d2i_IPAddressFamily, +d2i_IPAddressOrRange, +d2i_IPAddressRange, +d2i_ISSUING_DIST_POINT, +d2i_NETSCAPE_CERT_SEQUENCE, +d2i_NETSCAPE_SPKAC, +d2i_NETSCAPE_SPKI, +d2i_NOTICEREF, +d2i_OCSP_BASICRESP, +d2i_OCSP_CERTID, +d2i_OCSP_CERTSTATUS, +d2i_OCSP_CRLID, +d2i_OCSP_ONEREQ, +d2i_OCSP_REQINFO, +d2i_OCSP_REQUEST, +d2i_OCSP_RESPBYTES, +d2i_OCSP_RESPDATA, +d2i_OCSP_RESPID, +d2i_OCSP_RESPONSE, +d2i_OCSP_REVOKEDINFO, +d2i_OCSP_SERVICELOC, +d2i_OCSP_SIGNATURE, +d2i_OCSP_SINGLERESP, +d2i_OTHERNAME, +d2i_PBE2PARAM, +d2i_PBEPARAM, +d2i_PBKDF2PARAM, +d2i_PKCS12, +d2i_PKCS12_BAGS, +d2i_PKCS12_MAC_DATA, +d2i_PKCS12_SAFEBAG, +d2i_PKCS12_bio, +d2i_PKCS12_fp, +d2i_PKCS7, +d2i_PKCS7_DIGEST, +d2i_PKCS7_ENCRYPT, +d2i_PKCS7_ENC_CONTENT, +d2i_PKCS7_ENVELOPE, +d2i_PKCS7_ISSUER_AND_SERIAL, +d2i_PKCS7_RECIP_INFO, +d2i_PKCS7_SIGNED, +d2i_PKCS7_SIGNER_INFO, +d2i_PKCS7_SIGN_ENVELOPE, +d2i_PKCS7_bio, +d2i_PKCS7_fp, +d2i_PKCS8_PRIV_KEY_INFO, +d2i_PKCS8_PRIV_KEY_INFO_bio, +d2i_PKCS8_PRIV_KEY_INFO_fp, +d2i_PKCS8_bio, +d2i_PKCS8_fp, +d2i_PKEY_USAGE_PERIOD, +d2i_POLICYINFO, +d2i_POLICYQUALINFO, +d2i_PROXY_CERT_INFO_EXTENSION, +d2i_PROXY_POLICY, +d2i_RSAPrivateKey, +d2i_RSAPrivateKey_bio, +d2i_RSAPrivateKey_fp, +d2i_RSAPublicKey, +d2i_RSAPublicKey_bio, +d2i_RSAPublicKey_fp, +d2i_RSA_OAEP_PARAMS, +d2i_RSA_PSS_PARAMS, +d2i_RSA_PUBKEY, +d2i_RSA_PUBKEY_bio, +d2i_RSA_PUBKEY_fp, +d2i_SCT_LIST, +d2i_SXNET, +d2i_SXNETID, +d2i_TS_ACCURACY, +d2i_TS_MSG_IMPRINT, +d2i_TS_MSG_IMPRINT_bio, +d2i_TS_MSG_IMPRINT_fp, +d2i_TS_REQ, +d2i_TS_REQ_bio, +d2i_TS_REQ_fp, +d2i_TS_RESP, +d2i_TS_RESP_bio, +d2i_TS_RESP_fp, +d2i_TS_STATUS_INFO, +d2i_TS_TST_INFO, +d2i_TS_TST_INFO_bio, +d2i_TS_TST_INFO_fp, +d2i_USERNOTICE, +d2i_X509, +d2i_X509_ALGOR, +d2i_X509_ALGORS, +d2i_X509_ATTRIBUTE, +d2i_X509_CERT_AUX, +d2i_X509_CINF, +d2i_X509_CRL, +d2i_X509_CRL_INFO, +d2i_X509_CRL_bio, +d2i_X509_CRL_fp, +d2i_X509_EXTENSION, +d2i_X509_EXTENSIONS, +d2i_X509_NAME, +d2i_X509_NAME_ENTRY, +d2i_X509_PUBKEY, +d2i_X509_REQ, +d2i_X509_REQ_INFO, +d2i_X509_REQ_bio, +d2i_X509_REQ_fp, +d2i_X509_REVOKED, +d2i_X509_SIG, +d2i_X509_VAL, +i2d_ACCESS_DESCRIPTION, +i2d_ASIdOrRange, +i2d_ASIdentifierChoice, +i2d_ASIdentifiers, +i2d_ASN1_BIT_STRING, +i2d_ASN1_BMPSTRING, +i2d_ASN1_ENUMERATED, +i2d_ASN1_GENERALIZEDTIME, +i2d_ASN1_GENERALSTRING, +i2d_ASN1_IA5STRING, +i2d_ASN1_INTEGER, +i2d_ASN1_NULL, +i2d_ASN1_OBJECT, +i2d_ASN1_OCTET_STRING, +i2d_ASN1_PRINTABLE, +i2d_ASN1_PRINTABLESTRING, +i2d_ASN1_SEQUENCE_ANY, +i2d_ASN1_SET_ANY, +i2d_ASN1_T61STRING, +i2d_ASN1_TIME, +i2d_ASN1_TYPE, +i2d_ASN1_UNIVERSALSTRING, +i2d_ASN1_UTCTIME, +i2d_ASN1_UTF8STRING, +i2d_ASN1_VISIBLESTRING, +i2d_ASN1_bio_stream, +i2d_ASRange, +i2d_AUTHORITY_INFO_ACCESS, +i2d_AUTHORITY_KEYID, +i2d_BASIC_CONSTRAINTS, +i2d_CERTIFICATEPOLICIES, +i2d_CMS_ContentInfo, +i2d_CMS_ReceiptRequest, +i2d_CMS_bio, +i2d_CRL_DIST_POINTS, +i2d_DHxparams, +i2d_DIRECTORYSTRING, +i2d_DISPLAYTEXT, +i2d_DIST_POINT, +i2d_DIST_POINT_NAME, +i2d_DSAPrivateKey, +i2d_DSAPrivateKey_bio, +i2d_DSAPrivateKey_fp, +i2d_DSAPublicKey, +i2d_DSA_PUBKEY, +i2d_DSA_PUBKEY_bio, +i2d_DSA_PUBKEY_fp, +i2d_DSA_SIG, +i2d_DSAparams, +i2d_ECPKParameters, +i2d_ECParameters, +i2d_ECPrivateKey, +i2d_ECPrivateKey_bio, +i2d_ECPrivateKey_fp, +i2d_EC_PUBKEY, +i2d_EC_PUBKEY_bio, +i2d_EC_PUBKEY_fp, +i2d_EDIPARTYNAME, +i2d_ESS_CERT_ID, +i2d_ESS_ISSUER_SERIAL, +i2d_ESS_SIGNING_CERT, +i2d_EXTENDED_KEY_USAGE, +i2d_GENERAL_NAME, +i2d_GENERAL_NAMES, +i2d_IPAddressChoice, +i2d_IPAddressFamily, +i2d_IPAddressOrRange, +i2d_IPAddressRange, +i2d_ISSUING_DIST_POINT, +i2d_NETSCAPE_CERT_SEQUENCE, +i2d_NETSCAPE_SPKAC, +i2d_NETSCAPE_SPKI, +i2d_NOTICEREF, +i2d_OCSP_BASICRESP, +i2d_OCSP_CERTID, +i2d_OCSP_CERTSTATUS, +i2d_OCSP_CRLID, +i2d_OCSP_ONEREQ, +i2d_OCSP_REQINFO, +i2d_OCSP_REQUEST, +i2d_OCSP_RESPBYTES, +i2d_OCSP_RESPDATA, +i2d_OCSP_RESPID, +i2d_OCSP_RESPONSE, +i2d_OCSP_REVOKEDINFO, +i2d_OCSP_SERVICELOC, +i2d_OCSP_SIGNATURE, +i2d_OCSP_SINGLERESP, +i2d_OTHERNAME, +i2d_PBE2PARAM, +i2d_PBEPARAM, +i2d_PBKDF2PARAM, +i2d_PKCS12, +i2d_PKCS12_BAGS, +i2d_PKCS12_MAC_DATA, +i2d_PKCS12_SAFEBAG, +i2d_PKCS12_bio, +i2d_PKCS12_fp, +i2d_PKCS7, +i2d_PKCS7_DIGEST, +i2d_PKCS7_ENCRYPT, +i2d_PKCS7_ENC_CONTENT, +i2d_PKCS7_ENVELOPE, +i2d_PKCS7_ISSUER_AND_SERIAL, +i2d_PKCS7_NDEF, +i2d_PKCS7_RECIP_INFO, +i2d_PKCS7_SIGNED, +i2d_PKCS7_SIGNER_INFO, +i2d_PKCS7_SIGN_ENVELOPE, +i2d_PKCS7_bio, +i2d_PKCS7_fp, +i2d_PKCS8PrivateKeyInfo_bio, +i2d_PKCS8PrivateKeyInfo_fp, +i2d_PKCS8_PRIV_KEY_INFO, +i2d_PKCS8_PRIV_KEY_INFO_bio, +i2d_PKCS8_PRIV_KEY_INFO_fp, +i2d_PKCS8_bio, +i2d_PKCS8_fp, +i2d_PKEY_USAGE_PERIOD, +i2d_POLICYINFO, +i2d_POLICYQUALINFO, +i2d_PROXY_CERT_INFO_EXTENSION, +i2d_PROXY_POLICY, +i2d_PublicKey, +i2d_RSAPrivateKey, +i2d_RSAPrivateKey_bio, +i2d_RSAPrivateKey_fp, +i2d_RSAPublicKey, +i2d_RSAPublicKey_bio, +i2d_RSAPublicKey_fp, +i2d_RSA_OAEP_PARAMS, +i2d_RSA_PSS_PARAMS, +i2d_RSA_PUBKEY, +i2d_RSA_PUBKEY_bio, +i2d_RSA_PUBKEY_fp, +i2d_SCT_LIST, +i2d_SXNET, +i2d_SXNETID, +i2d_TS_ACCURACY, +i2d_TS_MSG_IMPRINT, +i2d_TS_MSG_IMPRINT_bio, +i2d_TS_MSG_IMPRINT_fp, +i2d_TS_REQ, +i2d_TS_REQ_bio, +i2d_TS_REQ_fp, +i2d_TS_RESP, +i2d_TS_RESP_bio, +i2d_TS_RESP_fp, +i2d_TS_STATUS_INFO, +i2d_TS_TST_INFO, +i2d_TS_TST_INFO_bio, +i2d_TS_TST_INFO_fp, +i2d_USERNOTICE, +i2d_X509, +i2d_X509_ALGOR, +i2d_X509_ALGORS, +i2d_X509_ATTRIBUTE, +i2d_X509_CERT_AUX, +i2d_X509_CINF, +i2d_X509_CRL, +i2d_X509_CRL_INFO, +i2d_X509_CRL_bio, +i2d_X509_CRL_fp, +i2d_X509_EXTENSION, +i2d_X509_EXTENSIONS, +i2d_X509_NAME, +i2d_X509_NAME_ENTRY, +i2d_X509_PUBKEY, +i2d_X509_REQ, +i2d_X509_REQ_INFO, +i2d_X509_REQ_bio, +i2d_X509_REQ_fp, +i2d_X509_REVOKED, +i2d_X509_SIG, +i2d_X509_VAL, +- convert objects from/to ASN.1/DER representation + +=head1 SYNOPSIS + +=for comment generic + + TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length); + TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); + TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); + + int i2d_TYPE(TYPE *a, unsigned char **ppout); + int i2d_TYPE_fp(FILE *fp, TYPE *a); + int i2d_TYPE_bio(BIO *bp, TYPE *a); + +=head1 DESCRIPTION + +In the description here, I<TYPE> is used a placeholder +for any of the OpenSSL datatypes, such as I<X509_CRL>. +The function parameters I<ppin> and I<ppout> are generally +either both named I<pp> in the headers, or I<in> and I<out>. + +These functions convert OpenSSL objects to and from their ASN.1/DER +encoding. Unlike the C structures which can have pointers to sub-objects +within, the DER is a serialized encoding, suitable for sending over the +network, writing to a file, and so on. + +d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a +pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to +the byte following the parsed data. If B<a> is not B<NULL> then a pointer +to the returned structure is also written to B<*a>. If an error occurred +then B<NULL> is returned. + +On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a> +contains a valid B<TYPE> structure and an attempt is made to reuse it. This +"reuse" capability is present for historical compatibility but its use is +B<strongly discouraged> (see BUGS below, and the discussion in the RETURN +VALUES section). + +d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts +to parse data from BIO B<bp>. + +d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts +to parse data from FILE pointer B<fp>. + +i2d_TYPE() encodes the structure pointed to by B<a> into DER format. +If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer +at B<*ppout>, and increments it to point after the data just written. +If the return value is negative an error occurred, otherwise it +returns the length of the encoded data. + +If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded +data written to it. In this case B<*ppout> is not incremented and it points +to the start of the data just written. + +i2d_TYPE_bio() is similar to i2d_TYPE() except it writes +the encoding of the structure B<a> to BIO B<bp> and it +returns 1 for success and 0 for failure. + +i2d_TYPE_fp() is similar to i2d_TYPE() except it writes +the encoding of the structure B<a> to BIO B<bp> and it +returns 1 for success and 0 for failure. + +These routines do not encrypt private keys and therefore offer no +security; use L<PEM_write_PrivateKey(3)> or similar for writing to files. + +=head1 NOTES + +The letters B<i> and B<d> in B<i2d_TYPE> stand for +"internal" (that is, an internal C structure) and "DER" respectively. +So B<i2d_TYPE> converts from internal to DER. + +The functions can also understand B<BER> forms. + +The actual TYPE structure passed to i2d_TYPE() must be a valid +populated B<TYPE> structure -- it B<cannot> simply be fed with an +empty structure such as that returned by TYPE_new(). + +The encoded data is in binary form and may contain embedded zeroes. +Therefore any FILE pointers or BIOs should be opened in binary mode. +Functions such as strlen() will B<not> return the correct length +of the encoded structure. + +The ways that B<*ppin> and B<*ppout> are incremented after the operation +can trap the unwary. See the B<WARNINGS> section for some common +errors. +The reason for this-auto increment behaviour is to reflect a typical +usage of ASN1 functions: after one structure is encoded or decoded +another will be processed after it. + +The following points about the data types might be useful: + +=over 4 + +=item B<ASN1_OBJECT> + +Represents an ASN1 OBJECT IDENTIFIER. + +=item B<DHparams> + +Represents a PKCS#3 DH parameters structure. + +=item B<DHparamx> + +Represents a ANSI X9.42 DH parameters structure. + +=item B<DSA_PUBKEY> + +Represents a DSA public key using a B<SubjectPublicKeyInfo> structure. + +=item B<DSAPublicKey, DSAPrivateKey> + +Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>, +B<PEM_write_PrivateKey(3)>, or similar instead. + +=item B<RSAPublicKey> + +Represents a PKCS#1 RSA public key structure. + +=item B<X509_ALGOR> + +Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and +elsewhere. + +=item B<X509_Name> + +Represents a B<Name> type as used for subject and issuer names in +IETF RFC 6960 and elsewhere. + +=item B<X509_REQ> + +Represents a PKCS#10 certificate request. + +=item B<X509_SIG> + +Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. + +=back + +=head1 EXAMPLES + +Allocate and encode the DER encoding of an X509 structure: + + int len; + unsigned char *buf; + + buf = NULL; + len = i2d_X509(x, &buf); + if (len < 0) + /* error */ + +Attempt to decode a buffer: + + X509 *x; + unsigned char *buf, *p; + int len; + + /* Set up buf and len to point to the input buffer. */ + p = buf; + x = d2i_X509(NULL, &p, len); + if (x == NULL) + /* error */ + +Alternative technique: + + X509 *x; + unsigned char *buf, *p; + int len; + + /* Set up buf and len to point to the input buffer. */ + p = buf; + x = NULL; + + if (d2i_X509(&x, &p, len) == NULL) + /* error */ + +=head1 WARNINGS + +Using a temporary variable is mandatory. A common +mistake is to attempt to use a buffer directly as follows: + + int len; + unsigned char *buf; + + len = i2d_X509(x, NULL); + buf = OPENSSL_malloc(len); + ... + i2d_X509(x, &buf); + ... + OPENSSL_free(buf); + +This code will result in B<buf> apparently containing garbage because +it was incremented after the call to point after the data just written. +Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc() +and the subsequent call to OPENSSL_free() is likely to crash. + +Another trap to avoid is misuse of the B<a> argument to d2i_TYPE(): + + X509 *x; + + if (d2i_X509(&x, &p, len) == NULL) + /* error */ + +This will probably crash somewhere in d2i_X509(). The reason for this +is that the variable B<x> is uninitialized and an attempt will be made to +interpret its (invalid) value as an B<X509> structure, typically causing +a segmentation violation. If B<x> is set to NULL first then this will not +happen. + +=head1 BUGS + +In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when +B<*px> is valid is broken and some parts of the reused structure may +persist if they are not present in the new one. As a result the use +of this "reuse" behaviour is strongly discouraged. + +i2d_TYPE() will not return an error in many versions of OpenSSL, +if mandatory fields are not initialized due to a programming error +then the encoded structure may contain invalid data or omit the +fields entirely and will not be parsed by d2i_TYPE(). This may be +fixed in future so code should not assume that i2d_TYPE() will +always succeed. + +Any function which encodes a structure (i2d_TYPE(), +i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the +structure has been modified after deserialization or previous +serialization. This is because some objects cache the encoding for +efficiency reasons. + +=head1 RETURN VALUES + +d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure +or B<NULL> if an error occurs. If the "reuse" capability has been used with +a valid structure being passed in via B<a>, then the object is not freed in +the event of error but may be in a potentially invalid or inconsistent state. + +i2d_TYPE() returns the number of bytes successfully encoded or a negative +value if an error occurs. + +i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error +occurs. + +=head1 COPYRIGHT + +Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/des_modes.pod b/openssl-1.1.0h/doc/crypto/des_modes.pod new file mode 100644 index 0000000..d5a3f8d --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/des_modes.pod @@ -0,0 +1,261 @@ +=pod + +=for comment openssl_manual_section:7 + +=head1 NAME + +des_modes - the variants of DES and other crypto algorithms of OpenSSL + +=head1 DESCRIPTION + +Several crypto algorithms for OpenSSL can be used in a number of modes. Those +are used for using block ciphers in a way similar to stream ciphers, among +other things. + +=head1 OVERVIEW + +=head2 Electronic Codebook Mode (ECB) + +Normally, this is found as the function I<algorithm>_ecb_encrypt(). + +=over 4 + +=item * + +64 bits are enciphered at a time. + +=item * + +The order of the blocks can be rearranged without detection. + +=item * + +The same plaintext block always produces the same ciphertext block +(for the same key) making it vulnerable to a 'dictionary attack'. + +=item * + +An error will only affect one ciphertext block. + +=back + +=head2 Cipher Block Chaining Mode (CBC) + +Normally, this is found as the function I<algorithm>_cbc_encrypt(). +Be aware that des_cbc_encrypt() is not really DES CBC (it does +not update the IV); use des_ncbc_encrypt() instead. + +=over 4 + +=item * + +a multiple of 64 bits are enciphered at a time. + +=item * + +The CBC mode produces the same ciphertext whenever the same +plaintext is encrypted using the same key and starting variable. + +=item * + +The chaining operation makes the ciphertext blocks dependent on the +current and all preceding plaintext blocks and therefore blocks can not +be rearranged. + +=item * + +The use of different starting variables prevents the same plaintext +enciphering to the same ciphertext. + +=item * + +An error will affect the current and the following ciphertext blocks. + +=back + +=head2 Cipher Feedback Mode (CFB) + +Normally, this is found as the function I<algorithm>_cfb_encrypt(). + +=over 4 + +=item * + +a number of bits (j) <= 64 are enciphered at a time. + +=item * + +The CFB mode produces the same ciphertext whenever the same +plaintext is encrypted using the same key and starting variable. + +=item * + +The chaining operation makes the ciphertext variables dependent on the +current and all preceding variables and therefore j-bit variables are +chained together and can not be rearranged. + +=item * + +The use of different starting variables prevents the same plaintext +enciphering to the same ciphertext. + +=item * + +The strength of the CFB mode depends on the size of k (maximal if +j == k). In my implementation this is always the case. + +=item * + +Selection of a small value for j will require more cycles through +the encipherment algorithm per unit of plaintext and thus cause +greater processing overheads. + +=item * + +Only multiples of j bits can be enciphered. + +=item * + +An error will affect the current and the following ciphertext variables. + +=back + +=head2 Output Feedback Mode (OFB) + +Normally, this is found as the function I<algorithm>_ofb_encrypt(). + +=over 4 + + +=item * + +a number of bits (j) <= 64 are enciphered at a time. + +=item * + +The OFB mode produces the same ciphertext whenever the same +plaintext enciphered using the same key and starting variable. More +over, in the OFB mode the same key stream is produced when the same +key and start variable are used. Consequently, for security reasons +a specific start variable should be used only once for a given key. + +=item * + +The absence of chaining makes the OFB more vulnerable to specific attacks. + +=item * + +The use of different start variables values prevents the same +plaintext enciphering to the same ciphertext, by producing different +key streams. + +=item * + +Selection of a small value for j will require more cycles through +the encipherment algorithm per unit of plaintext and thus cause +greater processing overheads. + +=item * + +Only multiples of j bits can be enciphered. + +=item * + +OFB mode of operation does not extend ciphertext errors in the +resultant plaintext output. Every bit error in the ciphertext causes +only one bit to be in error in the deciphered plaintext. + +=item * + +OFB mode is not self-synchronizing. If the two operation of +encipherment and decipherment get out of synchronism, the system needs +to be re-initialized. + +=item * + +Each re-initialization should use a value of the start variable +different from the start variable values used before with the same +key. The reason for this is that an identical bit stream would be +produced each time from the same parameters. This would be +susceptible to a 'known plaintext' attack. + +=back + +=head2 Triple ECB Mode + +Normally, this is found as the function I<algorithm>_ecb3_encrypt(). + +=over 4 + +=item * + +Encrypt with key1, decrypt with key2 and encrypt with key3 again. + +=item * + +As for ECB encryption but increases the key length to 168 bits. +There are theoretic attacks that can be used that make the effective +key length 112 bits, but this attack also requires 2^56 blocks of +memory, not very likely, even for the NSA. + +=item * + +If both keys are the same it is equivalent to encrypting once with +just one key. + +=item * + +If the first and last key are the same, the key length is 112 bits. +There are attacks that could reduce the effective key strength +to only slightly more than 56 bits, but these require a lot of memory. + +=item * + +If all 3 keys are the same, this is effectively the same as normal +ecb mode. + +=back + +=head2 Triple CBC Mode + +Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt(). + +=over 4 + +=item * + +Encrypt with key1, decrypt with key2 and then encrypt with key3. + +=item * + +As for CBC encryption but increases the key length to 168 bits with +the same restrictions as for triple ecb mode. + +=back + +=head1 NOTES + +This text was been written in large parts by Eric Young in his original +documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed +it to: + + AS 2805.5.2 + Australian Standard + Electronic funds transfer - Requirements for interfaces, + Part 5.2: Modes of operation for an n-bit block cipher algorithm + Appendix A + +=head1 SEE ALSO + +L<BF_encrypt(3)>, L<DES_crypt(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/evp.pod b/openssl-1.1.0h/doc/crypto/evp.pod new file mode 100644 index 0000000..02051df --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/evp.pod @@ -0,0 +1,116 @@ +=pod + +=for comment openssl_manual_section:7 + +=head1 NAME + +evp - high-level cryptographic functions + +=head1 SYNOPSIS + + #include <openssl/evp.h> + +=head1 DESCRIPTION + +The EVP library provides a high-level interface to cryptographic +functions. + +L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and L<B<EVP_Open>I<...>|EVP_OpenInit(3)> +provide public key encryption and decryption to implement digital "envelopes". + +The L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> and +L<B<EVP_DigestVerify>I<...>|EVP_DigestVerifyInit(3)> functions implement +digital signatures and Message Authentication Codes (MACs). Also see the older +L<B<EVP_Sign>I<...>|EVP_SignInit(3)> and L<B<EVP_Verify>I<...>|EVP_VerifyInit(3)> +functions. + +Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)> +functions. The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests. + +The B<EVP_PKEY>I<...> functions provide a high level interface to +asymmetric algorithms. To create a new EVP_PKEY see +L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated +with a private key of a particular algorithm by using the functions +described on the L<EVP_PKEY_set1_RSA(3)> page, or +new keys can be generated using L<EVP_PKEY_keygen(3)>. +EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)>, or printed using +L<EVP_PKEY_print_private(3)>. + +The EVP_PKEY functions support the full range of asymmetric algorithm operations: + +=over 4 + +=item For key agreement see L<EVP_PKEY_derive(3)> + +=item For signing and verifying see L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)>. +However, note that +these functions do not perform a digest of the data to be signed. Therefore +normally you would use the L<EVP_DigestSignInit(3)> +functions for this purpose. + +=item For encryption and decryption see L<EVP_PKEY_encrypt(3)> +and L<EVP_PKEY_decrypt(3)> respectively. However, note that +these functions perform encryption and decryption only. As public key +encryption is an expensive operation, normally you would wrap +an encrypted message in a "digital envelope" using the L<EVP_SealInit(3)> and +L<EVP_OpenInit(3)> functions. + +=back + +The L<EVP_BytesToKey(3)> function provides some limited support for password +based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible +implementation. However, new applications should not typically use this (preferring, for example, +PBKDF2 from PCKS#5). + +The L<B<EVP_Encode>I<...>|EVP_EncodeInit(3)> and +L<B<EVP_Decode>I<...>|EVP_EncodeInit(3)> functions implement base 64 encoding +and decoding. + +All the symmetric algorithms (ciphers), digests and asymmetric algorithms +(public key algorithms) can be replaced by L<engine(3)> modules providing alternative +implementations. If ENGINE implementations of ciphers or digests are registered +as defaults, then the various EVP functions will automatically use those +implementations automatically in preference to built in software +implementations. For more information, consult the engine(3) man page. + +Although low level algorithm specific functions exist for many algorithms +their use is discouraged. They cannot be used with an ENGINE and ENGINE +versions of new algorithms cannot be accessed using the low level functions. +Also makes code harder to adapt to new algorithms and some options are not +cleanly supported at the low level and some operations are more efficient +using the high level interface. + +=head1 SEE ALSO + +L<EVP_DigestInit(3)>, +L<EVP_EncryptInit(3)>, +L<EVP_OpenInit(3)>, +L<EVP_SealInit(3)>, +L<EVP_DigestSignInit(3)>, +L<EVP_SignInit(3)>, +L<EVP_VerifyInit(3)>, +L<EVP_EncodeInit(3)>, +L<EVP_PKEY_new(3)>, +L<EVP_PKEY_set1_RSA(3)>, +L<EVP_PKEY_keygen(3)>, +L<EVP_PKEY_print_private(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)>, +L<EVP_BytesToKey(3)>, +L<engine(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/i2d_CMS_bio_stream.pod b/openssl-1.1.0h/doc/crypto/i2d_CMS_bio_stream.pod new file mode 100644 index 0000000..ece7a48 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/i2d_CMS_bio_stream.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format + +=head1 SYNOPSIS + + #include <openssl/cms.h> + + int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); + +=head1 DESCRIPTION + +i2d_CMS_bio_stream() outputs a CMS_ContentInfo structure in BER format. + +It is otherwise identical to the function SMIME_write_CMS(). + +=head1 NOTES + +This function is effectively a version of the i2d_CMS_bio() supporting +streaming. + +=head1 BUGS + +The prefix "i2d" is arguably wrong because the function outputs BER format. + +=head1 RETURN VALUES + +i2d_CMS_bio_stream() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_verify(3)>, L<CMS_encrypt(3)> +L<CMS_decrypt(3)>, +L<SMIME_write_CMS(3)>, +L<PEM_write_bio_CMS_stream(3)> + +=head1 HISTORY + +i2d_CMS_bio_stream() was added to OpenSSL 1.0.0 + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/i2d_PKCS7_bio_stream.pod b/openssl-1.1.0h/doc/crypto/i2d_PKCS7_bio_stream.pod new file mode 100644 index 0000000..b42940a --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/i2d_PKCS7_bio_stream.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +i2d_PKCS7_bio_stream - output PKCS7 structure in BER format + +=head1 SYNOPSIS + + #include <openssl/pkcs7.h> + + int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); + +=head1 DESCRIPTION + +i2d_PKCS7_bio_stream() outputs a PKCS7 structure in BER format. + +It is otherwise identical to the function SMIME_write_PKCS7(). + +=head1 NOTES + +This function is effectively a version of the d2i_PKCS7_bio() supporting +streaming. + +=head1 BUGS + +The prefix "i2d" is arguably wrong because the function outputs BER format. + +=head1 RETURN VALUES + +i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)>, L<PKCS7_sign(3)>, +L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)>, +L<SMIME_write_PKCS7(3)>, +L<PEM_write_bio_PKCS7_stream(3)> + +=head1 HISTORY + +i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0 + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/i2d_re_X509_tbs.pod b/openssl-1.1.0h/doc/crypto/i2d_re_X509_tbs.pod new file mode 100644 index 0000000..672c7ab --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/i2d_re_X509_tbs.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +d2i_X509_AUX, i2d_X509_AUX, +i2d_re_X509_tbs, i2d_re_X509_CRL_tbs, i2d_re_X509_REQ_tbs +- X509 encode and decode functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); + int i2d_X509_AUX(X509 *x, unsigned char **out); + int i2d_re_X509_tbs(X509 *x, unsigned char **out); + int i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **pp); + int i2d_re_X509_REQ_tbs(X509_REQ *req, unsigned char **pp); + +=head1 DESCRIPTION + +The X509 encode and decode routines encode and parse an +B<X509> structure, which represents an X509 certificate. + +d2i_X509_AUX() is similar to L<d2i_X509(3)> but the input is expected to +consist of an X509 certificate followed by auxiliary trust information. +This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects. +This function should not be called on untrusted input. + +i2d_X509_AUX() is similar to L<i2d_X509(3)>, but the encoded output +contains both the certificate and any auxiliary trust information. +This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects. +Note that this is a non-standard OpenSSL-specific data format. + +i2d_re_X509_tbs() is similar to L<i2d_X509(3)> except it encodes only +the TBSCertificate portion of the certificate. i2d_re_X509_CRL_tbs() +and i2d_re_X509_REQ_tbs() are analogous for CRL and certificate request, +respectively. The "re" in B<i2d_re_X509_tbs> stands for "re-encode", +and ensures that a fresh encoding is generated in case the object has been +modified after creation (see the BUGS section). + +The encoding of the TBSCertificate portion of a certificate is cached +in the B<X509> structure internally to improve encoding performance +and to ensure certificate signatures are verified correctly in some +certificates with broken (non-DER) encodings. + +If, after modification, the B<X509> object is re-signed with X509_sign(), +the encoding is automatically renewed. Otherwise, the encoding of the +TBSCertificate portion of the B<X509> can be manually renewed by calling +i2d_re_X509_tbs(). + +=head1 SEE ALSO + +L<ERR_get_error(3)> +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/o2i_SCT_LIST.pod b/openssl-1.1.0h/doc/crypto/o2i_SCT_LIST.pod new file mode 100644 index 0000000..82922fc --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/o2i_SCT_LIST.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +o2i_SCT_LIST, i2o_SCT_LIST, o2i_SCT, i2o_SCT - +decode and encode Signed Certificate Timestamp lists in TLS wire format + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + STACK_OF(SCT) *o2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp, size_t len); + int i2o_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp); + SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len); + int i2o_SCT(const SCT *sct, unsigned char **out); + +=head1 DESCRIPTION + +The SCT_LIST and SCT functions are very similar to the i2d and d2i family of +functions, except that they convert to and from TLS wire format, as described in +RFC 6962. See L<d2i_SCT_LIST> for more information about how the parameters are +treated and the return values. + +=head1 RETURN VALUES + +All of the functions have return values consistent with those stated for +L<d2i_SCT_LIST> and L<i2d_SCT_LIST>. + +=head1 SEE ALSO + +L<ct(3)>, +L<d2i_SCT_LIST(3)>, +L<i2d_SCT_LIST(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/crypto/x509.pod b/openssl-1.1.0h/doc/crypto/x509.pod new file mode 100644 index 0000000..483b037 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/x509.pod @@ -0,0 +1,75 @@ +=pod + +=for comment openssl_manual_section:7 + +=head1 NAME + +x509 - X.509 certificate handling + +=head1 SYNOPSIS + + #include <openssl/x509.h> + +=head1 DESCRIPTION + +An X.509 certificate is a structured grouping of information about +an individual, a device, or anything one can imagine. A X.509 CRL +(certificate revocation list) is a tool to help determine if a +certificate is still valid. The exact definition of those can be +found in the X.509 document from ITU-T, or in RFC3280 from PKIX. +In OpenSSL, the type X509 is used to express such a certificate, and +the type X509_CRL is used to express a CRL. + +A related structure is a certificate request, defined in PKCS#10 from +RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type +X509_REQ is used to express such a certificate request. + +To handle some complex parts of a certificate, there are the types +X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express +a certificate attributes), X509_EXTENSION (to express a certificate +extension) and a few more. + +Finally, there's the supertype X509_INFO, which can contain a CRL, a +certificate and a corresponding private key. + +B<X509_>I<...>, B<d2i_X509_>I<...> and B<i2d_X509_>I<...> handle X.509 +certificates, with some exceptions, shown below. + +B<X509_CRL_>I<...>, B<d2i_X509_CRL_>I<...> and B<i2d_X509_CRL_>I<...> +handle X.509 CRLs. + +B<X509_REQ_>I<...>, B<d2i_X509_REQ_>I<...> and B<i2d_X509_REQ_>I<...> +handle PKCS#10 certificate requests. + +B<X509_NAME_>I<...> handle certificate names. + +B<X509_ATTRIBUTE_>I<...> handle certificate attributes. + +B<X509_EXTENSION_>I<...> handle certificate extensions. + +=head1 SEE ALSO + +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_add_entry_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_NAME_new(3)>, +L<d2i_X509(3)>, +L<d2i_X509_ALGOR(3)>, +L<d2i_X509_CRL(3)>, +L<d2i_X509_NAME(3)>, +L<d2i_X509_REQ(3)>, +L<d2i_X509_SIG(3)>, +L<X509v3(3)>, +L<crypto(7)> + +=head1 COPYRIGHT + +Copyright 2003-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/dir-locals.example.el b/openssl-1.1.0h/doc/dir-locals.example.el new file mode 100644 index 0000000..dc0d554 --- /dev/null +++ b/openssl-1.1.0h/doc/dir-locals.example.el @@ -0,0 +1,15 @@ +;;; This is an example of what a .dir-locals.el suitable for OpenSSL +;;; development could look like. +;;; +;;; Apart from setting the CC mode style to "OpenSSL-II", it also +;;; makes sure that tabs are never used for indentation in any file, +;;; and that the fill column is 78. +;;; +;;; For more information see (info "(emacs) Directory Variables") + +((nil + (indent-tabs-mode . nil) + (fill-column . 70) + ) + (c-mode + (c-file-style . "OpenSSL-II"))) diff --git a/openssl-1.1.0h/doc/fingerprints.txt b/openssl-1.1.0h/doc/fingerprints.txt new file mode 100644 index 0000000..1863224 --- /dev/null +++ b/openssl-1.1.0h/doc/fingerprints.txt @@ -0,0 +1,27 @@ +Fingerprints for Signing Releases + +OpenSSL releases are signed with PGP/GnuPG keys. This file contains +the fingerprints of team members who are "authorized" to sign the +next release. + +The signature is a detached cleartxt signature, with the same name +as the release but with ".asc" appended. For example, release +1.0.1h can be found in openssl-1.0.1h.tar.gz with the signature +in the file named openssl-1.0.1h.tar.gz.asc. + +The following is the list of fingerprints for the keys that are +currently in use to sign OpenSSL distributions: + +pub 4096R/7DF9EE8C 2014-10-04 + Key fingerprint = 7953 AC1F BC3D C8B3 B292 393E D5E9 E43F 7DF9 EE8C +uid Richard Levitte <richard@opensslfoundation.com> +uid Richard Levitte <levitte@openssl.org> +uid Richard Levitte <richard@openssl.com> + +pub 4096R/FA40E9E2 2005-03-19 + Key fingerprint = 6260 5AA4 334A F9F0 DDE5 D349 D357 7507 FA40 E9E2 +uid Dr Stephen N Henson <steve@openssl.org> + +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/openssl-1.1.0h/doc/openssl-c-indent.el b/openssl-1.1.0h/doc/openssl-c-indent.el new file mode 100644 index 0000000..cca1183 --- /dev/null +++ b/openssl-1.1.0h/doc/openssl-c-indent.el @@ -0,0 +1,62 @@ +;;; This Emacs Lisp file defines a C indentation style for OpenSSL. +;;; +;;; This definition is for the "CC mode" package, which is the default +;;; mode for editing C source files in Emacs 20, not for the older +;;; c-mode.el (which was the default in less recent release of Emacs 19). +;;; +;;; Recommended use is to add this line in your .emacs: +;;; +;;; (load (expand-file-name "~/PATH/TO/openssl-c-indent.el")) +;;; +;;; To activate this indentation style, visit a C file, type +;;; M-x c-set-style <RET> (or C-c . for short), and enter "eay". +;;; To toggle the auto-newline feature of CC mode, type C-c C-a. +;;; +;;; If you're an OpenSSL developer, you might find it more comfortable +;;; to have this style be permanent in your OpenSSL development +;;; directory. To have that, please perform this: +;;; +;;; M-x add-dir-local-variable <RET> c-mode <RET> c-file-style <RET> +;;; "OpenSSL-II" <RET> +;;; +;;; A new buffer with .dir-locals.el will appear. Save it (C-x C-s). +;;; +;;; Alternatively, have a look at dir-locals.example.el + +;;; For suggesting improvements, please send e-mail to levitte@openssl.org. + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; Note, it could be easy to inherit from the "gnu" style... however, +;; one never knows if that style will change somewhere in the future, +;; so I've chosen to copy the "gnu" style values explicitly instead +;; and mark them with a comment. // RLevitte 2015-08-31 +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + +(c-add-style "OpenSSL-II" + '((c-basic-offset . 4) + (indent-tabs-mode . nil) + (fill-column . 78) + (comment-column . 33) + (c-comment-only-line-offset 0 . 0) ; From "gnu" style + (c-hanging-braces-alist ; From "gnu" style + (substatement-open before after) ; From "gnu" style + (arglist-cont-nonempty)) ; From "gnu" style + (c-offsets-alist + (statement-block-intro . +) ; From "gnu" style + (knr-argdecl-intro . 0) + (knr-argdecl . 0) + (substatement-open . +) ; From "gnu" style + (substatement-label . 0) ; From "gnu" style + (label . 1) + (statement-case-open . +) ; From "gnu" style + (statement-cont . +) ; From "gnu" style + (arglist-intro . c-lineup-arglist-intro-after-paren) ; From "gnu" style + (arglist-close . c-lineup-arglist) ; From "gnu" style + (inline-open . 0) ; From "gnu" style + (brace-list-open . +) ; From "gnu" style + (topmost-intro-cont first c-lineup-topmost-intro-cont + c-lineup-gnu-DEFUN-intro-cont) ; From "gnu" style + ) + (c-special-indent-hook . c-gnu-impose-minimum) ; From "gnu" style + (c-block-comment-prefix . "* ") + )) diff --git a/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod b/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod new file mode 100644 index 0000000..a839d9f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +DTLSv1_listen - listen for incoming DTLS connections + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer); + +=head1 DESCRIPTION + +DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is +received that does not contain a cookie, then DTLSv1_listen() responds with a +HelloVerifyRequest. If a ClientHello is received with a cookie that is verified +then control is returned to user code to enable the handshake to be completed +(for example by using SSL_accept()). + +=head1 NOTES + +Datagram based protocols can be susceptible to Denial of Service attacks. A +DTLS attacker could, for example, submit a series of handshake initiation +requests that cause the server to allocate state (and possibly perform +cryptographic operations) thus consuming server resources. The attacker could +also (with UDP) quite simply forge the source IP address in such an attack. + +As a counter measure to that DTLS includes a stateless cookie mechanism. The +idea is that when a client attempts to connect to a server it sends a +ClientHello message. The server responds with a HelloVerifyRequest which +contains a unique cookie. The client then resends the ClientHello, but this time +includes the cookie in the message thus proving that the client is capable of +receiving messages sent to that address. All of this can be done by the server +without allocating any state, and thus without consuming expensive resources. + +OpenSSL implements this capability via the DTLSv1_listen() function. The B<ssl> +parameter should be a newly allocated SSL object with its read and write BIOs +set, in the same way as might be done for a call to SSL_accept(). Typically the +read BIO will be in an "unconnected" state and thus capable of receiving +messages from any peer. + +When a ClientHello is received that contains a cookie that has been verified, +then DTLSv1_listen() will return with the B<ssl> parameter updated into a state +where the handshake can be continued by a call to (for example) SSL_accept(). +Additionally the B<BIO_ADDR> pointed to by B<peer> will be filled in with +details of the peer that sent the ClientHello. If the underlying BIO is unable +to obtain the B<BIO_ADDR> of the peer (for example because the BIO does not +support this), then B<*peer> will be cleared and the family set to AF_UNSPEC. +Typically user code is expected to "connect" the underlying socket to the peer +and continue the handshake in a connected state. + +Prior to calling DTLSv1_listen() user code must ensure that cookie generation +and verification callbacks have been set up using +SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb() +respectively. + +Since DTLSv1_listen() operates entirely statelessly whilst processing incoming +ClientHellos it is unable to process fragmented messages (since this would +require the allocation of state). An implication of this is that DTLSv1_listen() +B<only> supports ClientHellos that fit inside a single datagram. + +=head1 RETURN VALUES + +From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance +the B<peer> value will be filled in and the B<ssl> object set up ready to +continue the handshake. + +A return value of 0 indicates a non-fatal error. This could (for +example) be because of non-blocking IO, or some invalid message having been +received from a peer. Errors may be placed on the OpenSSL error queue with +further information if appropriate. Typically user code is expected to retry the +call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the +error queue will be cleared in the subsequent call. + +A return value of <0 indicates a fatal error. This could (for example) be +because of a failure to allocate sufficient memory for the operation. + +Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes +<= 0 (in typical implementations user code treats all errors as non-fatal), +whilst return codes >0 indicate success. + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_accept(3)>, +L<ssl(3)>, L<bio(3)> + +=head1 HISTORY + +DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer" +also changed in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod b/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod new file mode 100644 index 0000000..b963e5e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +OPENSSL_init_ssl - OpenSSL (libssl and libcrypto) initialisation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); + +=head1 DESCRIPTION + +During normal operation OpenSSL (libssl and libcrypto) will allocate various +resources at start up that must, subsequently, be freed on close down of the +library. Additionally some resources are allocated on a per thread basis (if the +application is multi-threaded), and these resources must be freed prior to the +thread closing. + +As of version 1.1.0 OpenSSL will automatically allocate all resources that it +needs so no explicit initialisation is required. Similarly it will also +automatically deinitialise as required. + +However, there may be situations when explicit initialisation is desirable or +needed, for example when some non-default initialisation is required. The +function OPENSSL_init_ssl() can be used for this purpose. Calling +this function will explicitly initialise BOTH libcrypto and libssl. To +explicitly initialise ONLY libcrypto see the +L<OPENSSL_init_crypto(3)> function. + +Numerous internal OpenSSL functions call OPENSSL_init_ssl(). +Therefore, in order to perform non-default initialisation, +OPENSSL_init_ssl() MUST be called by application code prior to +any other OpenSSL function calls. + +The B<opts> parameter specifies which aspects of libssl and libcrypto should be +initialised. Valid options for libcrypto are described on the +L<OPENSSL_init_crypto(3)> page. In addition to any libcrypto +specific option the following libssl options can also be used: + +=over 4 + +=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS + +Suppress automatic loading of the libssl error strings. This option is +not a default option. Once selected subsequent calls to +OPENSSL_init_ssl() with the option +B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored. + +=item OPENSSL_INIT_LOAD_SSL_STRINGS + +Automatic loading of the libssl error strings. This option is a +default option. Once selected subsequent calls to +OPENSSL_init_ssl() with the option +B<OPENSSL_INIT_LOAD_SSL_STRINGS> will be ignored. + +=back + +OPENSSL_init_ssl() takes a B<settings> parameter which can be used to +set parameter values. See L<OPENSSL_init_crypto(3)> for details. + +=head1 RETURN VALUES + +The function OPENSSL_init_ssl() returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L<OPENSSL_init_crypto(3)> + +=head1 HISTORY + +The OPENSSL_init_ssl() function was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod b/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod new file mode 100644 index 0000000..b7ee3c8 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +SSL_CIPHER_get_cipher_nid, SSL_CIPHER_get_digest_nid, SSL_CIPHER_get_kx_nid, +SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead, +SSL_CIPHER_get_name, SSL_CIPHER_get_bits, +SSL_CIPHER_get_version, SSL_CIPHER_description +- get SSL_CIPHER properties + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); + int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits); + char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); + char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size); + int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c); + int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c); + int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c); + int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c); + int SSL_CIPHER_is_aead(const SSL_CIPHER *c); + +=head1 DESCRIPTION + +SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the +B<cipher> is NULL, it returns "(NONE)". + +SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. +If B<cipher> is NULL, 0 is returned. + +SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol +version that first defined the cipher. It returns "(NONE)" if B<cipher> is NULL. + +SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>. +If there is no cipher (e.g. for ciphersuites with no encryption) then +B<NID_undef> is returned. + +SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC +used by B<c>. If there is no digest (e.g. for AEAD ciphersuites) then +B<NID_undef> is returned. + +SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method +used by B<c>. If there is no key exchange, then B<NID_undef> is returned. Examples (not comprehensive): + + NID_kx_rsa + NID_kx_ecdhe + NID_kx_dhe + NID_kx_psk + +SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method +used by B<c>. If there is no authentication, then B<NID_undef> is returned. +Examples (not comprehensive): + + NID_auth_rsa + NID_auth_ecdsa + NID_auth_psk + +SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or +ChaCha20/Poly1305), and 0 if it is not AEAD. + +SSL_CIPHER_description() returns a textual description of the cipher used +into the buffer B<buf> of length B<len> provided. If B<buf> is provided, it +must be at least 128 bytes, otherwise a buffer will be allocated using +OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails, +B<NULL> is returned. + +The string returned by SSL_CIPHER_description() consists of several fields +separated by whitespace: + +=over 4 + +=item <ciphername> + +Textual representation of the cipher name. + +=item <protocol version> + +Protocol version, such as B<TLSv1.2>, when the cipher was first defined. + +=item Kx=<key exchange> + +Key exchange method such as B<RSA>, B<ECDHE>, etc. + +=item Au=<authentication> + +Authentication method such as B<RSA>, B<None>, etc.. None is the +representation of anonymous ciphers. + +=item Enc=<symmetric encryption method> + +Encryption method, with number of secret bits, such as B<AESGCM(128)>. + +=item Mac=<message authentication code> + +Message digest, such as B<SHA256>. + +=back + +Some examples for the output of SSL_CIPHER_description(): + + ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD + RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384 + +=head1 HISTORY + +SSL_CIPHER_get_version() was updated to always return the correct protocol +string in OpenSSL 1.1. + +SSL_CIPHER_description() was changed to return B<NULL> on error, +rather than a fixed string, in OpenSSL 1.1 + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_get_current_cipher(3)>, +L<SSL_get_ciphers(3)>, L<ciphers(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod b/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod new file mode 100644 index 0000000..15929df --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod @@ -0,0 +1,116 @@ +=pod + +=head1 NAME + +SSL_COMP_add_compression_method, SSL_COMP_get_compression_methods, +SSL_COMP_get0_name, SSL_COMP_get_id, SSL_COMP_free_compression_methods +- handle SSL/TLS integrated compression methods + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm); + STACK_OF(SSL_COMP) *SSL_COMP_get_compression_methods(void); + const char *SSL_COMP_get0_name(const SSL_COMP *comp); + int SSL_COMP_get_id(const SSL_COMP *comp); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + void SSL_COMP_free_compression_methods(void) + #endif + +=head1 DESCRIPTION + +SSL_COMP_add_compression_method() adds the compression method B<cm> with +the identifier B<id> to the list of available compression methods. This +list is globally maintained for all SSL operations within this application. +It cannot be set for specific SSL_CTX or SSL objects. + +SSL_COMP_get_compression_methods() returns a stack of all of the available +compression methods or NULL on error. + +SSL_COMP_get0_name() returns the name of the compression method B<comp>. + +SSL_COMP_get_id() returns the id of the compression method B<comp>. + +In versions of OpenSSL prior to 1.1.0 SSL_COMP_free_compression_methods() freed +the internal table of compression methods that were built internally, and +possibly augmented by adding SSL_COMP_add_compression_method(). However this is +now unnecessary from version 1.1.0. No explicit initialisation or +de-initialisation is necessary. See L<OPENSSL_init_crypto(3)> and +L<OPENSSL_init_ssl(3)>. From OpenSSL 1.1.0 calling this function does nothing. + +=head1 NOTES + +The TLS standard (or SSLv3) allows the integration of compression methods +into the communication. The TLS RFC does however not specify compression +methods or their corresponding identifiers, so there is currently no compatible +way to integrate compression with unknown peers. It is therefore currently not +recommended to integrate compression into applications. Applications for +non-public use may agree on certain compression methods. Using different +compression methods with the same identifier will lead to connection failure. + +An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1) +will unconditionally send the list of all compression methods enabled with +SSL_COMP_add_compression_method() to the server during the handshake. +Unlike the mechanisms to set a cipher list, there is no method available to +restrict the list of compression method on a per connection basis. + +An OpenSSL server will match the identifiers listed by a client against +its own compression methods and will unconditionally activate compression +when a matching identifier is found. There is no way to restrict the list +of compression methods supported on a per connection basis. + +If enabled during compilation, the OpenSSL library will have the +COMP_zlib() compression method available. + +=head1 WARNINGS + +Once the identities of the compression methods for the TLS protocol have +been standardized, the compression API will most likely be changed. Using +it in the current state is not recommended. + +=head1 RETURN VALUES + +SSL_COMP_add_compression_method() may return the following values: + +=over 4 + +=item Z<>0 + +The operation succeeded. + +=item Z<>1 + +The operation failed. Check the error queue to find out the reason. + +=back + +SSL_COMP_get_compression_methods() returns the stack of compressions methods or +NULL on error. + +SSL_COMP_get0_name() returns the name of the compression method or NULL on error. + +SSL_COMP_get_id() returns the name of the compression method or -1 on error. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 HISTORY + +SSL_COMP_free_compression_methods() was deprecated in OpenSSL 1.1.0. +SSL_COMP_get0_name() and SSL_comp_get_id() were added in OpenSSL 1.1.0d. + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod new file mode 100644 index 0000000..79f0bbc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_CONF_CTX_new, SSL_CONF_CTX_free - SSL configuration allocation functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_CONF_CTX *SSL_CONF_CTX_new(void); + void SSL_CONF_CTX_free(SSL_CONF_CTX *cctx); + +=head1 DESCRIPTION + +The function SSL_CONF_CTX_new() allocates and initialises an B<SSL_CONF_CTX> +structure for use with the SSL_CONF functions. + +The function SSL_CONF_CTX_free() frees up the context B<cctx>. +If B<cctx> is NULL nothing is done. + +=head1 RETURN VALUES + +SSL_CONF_CTX_new() returns either the newly allocated B<SSL_CONF_CTX> structure +or B<NULL> if an error occurs. + +SSL_CONF_CTX_free() does not return a value. + +=head1 SEE ALSO + +L<SSL_CONF_CTX_set_flags(3)>, +L<SSL_CONF_CTX_set_ssl_ctx(3)>, +L<SSL_CONF_CTX_set1_prefix(3)>, +L<SSL_CONF_cmd(3)>, +L<SSL_CONF_cmd_argv(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod new file mode 100644 index 0000000..da9e580 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +SSL_CONF_CTX_set1_prefix - Set configuration context command prefix + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + unsigned int SSL_CONF_CTX_set1_prefix(SSL_CONF_CTX *cctx, const char *prefix); + +=head1 DESCRIPTION + +The function SSL_CONF_CTX_set1_prefix() sets the command prefix of B<cctx> +to B<prefix>. If B<prefix> is B<NULL> it is restored to the default value. + +=head1 NOTES + +Command prefixes alter the commands recognised by subsequent SSL_CTX_cmd() +calls. For example for files, if the prefix "SSL" is set then command names +such as "SSLProtocol", "SSLOptions" etc. are recognised instead of "Protocol" +and "Options". Similarly for command lines if the prefix is "--ssl-" then +"--ssl-no_tls1_2" is recognised instead of "-no_tls1_2". + +If the B<SSL_CONF_FLAG_CMDLINE> flag is set then prefix checks are case +sensitive and "-" is the default. In the unlikely even an application +explicitly wants to set no prefix it must be explicitly set to "". + +If the B<SSL_CONF_FLAG_FILE> flag is set then prefix checks are case +insensitive and no prefix is the default. + +=head1 RETURN VALUES + +SSL_CONF_CTX_set1_prefix() returns 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<SSL_CONF_CTX_new(3)>, +L<SSL_CONF_CTX_set_flags(3)>, +L<SSL_CONF_CTX_set_ssl_ctx(3)>, +L<SSL_CONF_cmd(3)>, +L<SSL_CONF_cmd_argv(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod new file mode 100644 index 0000000..efd8da3 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +SSL_CONF_CTX_set_flags, SSL_CONF_CTX_clear_flags - Set of clear SSL configuration context flags + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + unsigned int SSL_CONF_CTX_set_flags(SSL_CONF_CTX *cctx, unsigned int flags); + unsigned int SSL_CONF_CTX_clear_flags(SSL_CONF_CTX *cctx, unsigned int flags); + +=head1 DESCRIPTION + +The function SSL_CONF_CTX_set_flags() sets B<flags> in the context B<cctx>. + +The function SSL_CONF_CTX_clear_flags() clears B<flags> in the context B<cctx>. + +=head1 NOTES + +The flags set affect how subsequent calls to SSL_CONF_cmd() or +SSL_CONF_argv() behave. + +Currently the following B<flags> values are recognised: + +=over 4 + +=item SSL_CONF_FLAG_CMDLINE, SSL_CONF_FLAG_FILE + +recognise options intended for command line or configuration file use. At +least one of these flags must be set. + +=item SSL_CONF_FLAG_CLIENT, SSL_CONF_FLAG_SERVER + +recognise options intended for use in SSL/TLS clients or servers. One or +both of these flags must be set. + +=item SSL_CONF_FLAG_CERTIFICATE + +recognise certificate and private key options. + +=item SSL_CONF_FLAG_REQUIRE_PRIVATE + +If this option is set then if a private key is not specified for a certificate +it will attempt to load a private key from the certificate file when +SSL_CONF_CTX_finish() is called. If a key cannot be loaded from the certificate +file an error occurs. + +=item SSL_CONF_FLAG_SHOW_ERRORS + +indicate errors relating to unrecognised options or missing arguments in +the error queue. If this option isn't set such errors are only reflected +in the return values of SSL_CONF_set_cmd() or SSL_CONF_set_argv() + +=back + +=head1 RETURN VALUES + +SSL_CONF_CTX_set_flags() and SSL_CONF_CTX_clear_flags() returns the new flags +value after setting or clearing flags. + +=head1 SEE ALSO + +L<SSL_CONF_CTX_new(3)>, +L<SSL_CONF_CTX_set_ssl_ctx(3)>, +L<SSL_CONF_CTX_set1_prefix(3)>, +L<SSL_CONF_cmd(3)>, +L<SSL_CONF_cmd_argv(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod new file mode 100644 index 0000000..7e4120f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +SSL_CONF_CTX_set_ssl_ctx, SSL_CONF_CTX_set_ssl - set context to configure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CONF_CTX_set_ssl_ctx(SSL_CONF_CTX *cctx, SSL_CTX *ctx); + void SSL_CONF_CTX_set_ssl(SSL_CONF_CTX *cctx, SSL *ssl); + +=head1 DESCRIPTION + +SSL_CONF_CTX_set_ssl_ctx() sets the context associated with B<cctx> to the +B<SSL_CTX> structure B<ctx>. Any previous B<SSL> or B<SSL_CTX> associated with +B<cctx> is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to +B<ctx>. + +SSL_CONF_CTX_set_ssl() sets the context associated with B<cctx> to the +B<SSL> structure B<ssl>. Any previous B<SSL> or B<SSL_CTX> associated with +B<cctx> is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to +B<ssl>. + +=head1 NOTES + +The context need not be set or it can be set to B<NULL> in which case only +syntax checking of commands is performed, where possible. + +=head1 RETURN VALUES + +SSL_CONF_CTX_set_ssl_ctx() and SSL_CTX_set_ssl() do not return a value. + +=head1 SEE ALSO + +L<SSL_CONF_CTX_new(3)>, +L<SSL_CONF_CTX_set_flags(3)>, +L<SSL_CONF_CTX_set1_prefix(3)>, +L<SSL_CONF_cmd(3)>, +L<SSL_CONF_cmd_argv(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod new file mode 100644 index 0000000..a28e218 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod @@ -0,0 +1,563 @@ +=pod + +=head1 NAME + +SSL_CONF_cmd_value_type, SSL_CONF_finish, +SSL_CONF_cmd - send configuration command + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value); + int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd); + int SSL_CONF_finish(SSL_CONF_CTX *cctx); + +=head1 DESCRIPTION + +The function SSL_CONF_cmd() performs configuration operation B<cmd> with +optional parameter B<value> on B<ctx>. Its purpose is to simplify application +configuration of B<SSL_CTX> or B<SSL> structures by providing a common +framework for command line options or configuration files. + +SSL_CONF_cmd_value_type() returns the type of value that B<cmd> refers to. + +The function SSL_CONF_finish() must be called after all configuration +operations have been completed. It is used to finalise any operations +or to process defaults. + +=head1 SUPPORTED COMMAND LINE COMMANDS + +Currently supported B<cmd> names for command lines (i.e. when the +flag B<SSL_CONF_CMDLINE> is set) are listed below. Note: all B<cmd> names +are case sensitive. Unless otherwise stated commands can be used by +both clients and servers and the B<value> parameter is not used. The default +prefix for command line commands is B<-> and that is reflected below. + +=over 4 + +=item B<-sigalgs> + +This sets the supported signature algorithms for TLS v1.2. For clients this +value is used directly for the supported signature algorithms extension. For +servers it is used to determine which signature algorithms to support. + +The B<value> argument should be a colon separated list of signature algorithms +in order of decreasing preference of the form B<algorithm+hash>. B<algorithm> +is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm +OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>. +Note: algorithm and hash names are case sensitive. + +If this option is not set then all signature algorithms supported by the +OpenSSL library are permissible. + +=item B<-client_sigalgs> + +This sets the supported signature algorithms associated with client +authentication for TLS v1.2. For servers the value is used in the supported +signature algorithms field of a certificate request. For clients it is +used to determine which signature algorithm to with the client certificate. +If a server does not request a certificate this option has no effect. + +The syntax of B<value> is identical to B<-sigalgs>. If not set then +the value set for B<-sigalgs> will be used instead. + +=item B<-curves> + +This sets the supported elliptic curves. For clients the curves are +sent using the supported curves extension. For servers it is used +to determine which curve to use. This setting affects curves used for both +signatures and key exchange, if applicable. + +The B<value> argument is a colon separated list of curves. The curve can be +either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g +B<prime256v1>). Curve names are case sensitive. + +=item B<-named_curve> + +This sets the temporary curve used for ephemeral ECDH modes. Only used by +servers + +The B<value> argument is a curve name or the special value B<auto> which +picks an appropriate curve based on client and server preferences. The curve +can be either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name +(e.g B<prime256v1>). Curve names are case sensitive. + +=item B<-cipher> + +Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is +currently not performed unless a B<SSL> or B<SSL_CTX> structure is +associated with B<cctx>. + +=item B<-cert> + +Attempts to use the file B<value> as the certificate for the appropriate +context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX> +structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL> +structure is set. This option is only supported if certificate operations +are permitted. + +=item B<-key> + +Attempts to use the file B<value> as the private key for the appropriate +context. This option is only supported if certificate operations +are permitted. Note: if no B<-key> option is set then a private key is +not loaded unless the flag B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set. + +=item B<-dhparam> + +Attempts to use the file B<value> as the set of temporary DH parameters for +the appropriate context. This option is only supported if certificate +operations are permitted. + +=item B<-no_renegotiation> + +Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting +B<SSL_OP_NO_RENEGOTIATION>. + +=item B<-min_protocol>, B<-max_protocol> + +Sets the minimum and maximum supported protocol. +Currently supported protocol values are B<SSLv3>, B<TLSv1>, +B<TLSv1.1>, B<TLSv1.2> for TLS and B<DTLSv1>, B<DTLSv1.2> for DTLS, +and B<None> for no limit. +If the either bound is not specified then only the other bound applies, +if specified. +To restrict the supported protocol versions use these commands rather +than the deprecated alternative commands below. + +=item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> + +Disables protocol support for SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2 by setting the +corresponding options B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> +and B<SSL_OP_NO_TLSv1_2> respectively. +These options are deprecated, instead use B<-min_protocol> and B<-max_protocol>. + +=item B<-bugs> + +Various bug workarounds are set, same as setting B<SSL_OP_ALL>. + +=item B<-comp> + +Enables support for SSL/TLS compression, same as clearing +B<SSL_OP_NO_COMPRESSION>. +This command was introduced in OpenSSL 1.1.0. +As of OpenSSL 1.1.0, compression is off by default. + +=item B<-no_comp> + +Disables support for SSL/TLS compression, same as setting +B<SSL_OP_NO_COMPRESSION>. +As of OpenSSL 1.1.0, compression is off by default. + +=item B<-no_ticket> + +Disables support for session tickets, same as setting B<SSL_OP_NO_TICKET>. + +=item B<-serverpref> + +Use server and not client preference order when determining which cipher suite, +signature algorithm or elliptic curve to use for an incoming connection. +Equivalent to B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers. + +=item B<-no_resumption_on_reneg> + +set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers. + +=item B<-legacyrenegotiation> + +permits the use of unsafe legacy renegotiation. Equivalent to setting +B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>. + +=item B<-legacy_server_connect>, B<-no_legacy_server_connect> + +permits or prohibits the use of unsafe legacy renegotiation for OpenSSL +clients only. Equivalent to setting or clearing B<SSL_OP_LEGACY_SERVER_CONNECT>. +Set by default. + +=item B<-strict> + +enables strict mode protocol handling. Equivalent to setting +B<SSL_CERT_FLAG_TLS_STRICT>. + +=back + +=head1 SUPPORTED CONFIGURATION FILE COMMANDS + +Currently supported B<cmd> names for configuration files (i.e. when the +flag B<SSL_CONF_FLAG_FILE> is set) are listed below. All configuration file +B<cmd> names are case insensitive so B<signaturealgorithms> is recognised +as well as B<SignatureAlgorithms>. Unless otherwise stated the B<value> names +are also case insensitive. + +Note: the command prefix (if set) alters the recognised B<cmd> values. + +=over 4 + +=item B<CipherString> + +Sets the cipher suite list to B<value>. Note: syntax checking of B<value> is +currently not performed unless an B<SSL> or B<SSL_CTX> structure is +associated with B<cctx>. + +=item B<Certificate> + +Attempts to use the file B<value> as the certificate for the appropriate +context. It currently uses SSL_CTX_use_certificate_chain_file() if an B<SSL_CTX> +structure is set or SSL_use_certificate_file() with filetype PEM if an B<SSL> +structure is set. This option is only supported if certificate operations +are permitted. + +=item B<PrivateKey> + +Attempts to use the file B<value> as the private key for the appropriate +context. This option is only supported if certificate operations +are permitted. Note: if no B<PrivateKey> option is set then a private key is +not loaded unless the B<SSL_CONF_FLAG_REQUIRE_PRIVATE> is set. + +=item B<ChainCAFile>, B<ChainCAPath>, B<VerifyCAFile>, B<VerifyCAPath> + +These options indicate a file or directory used for building certificate +chains or verifying certificate chains. These options are only supported +if certificate operations are permitted. + +=item B<ServerInfoFile> + +Attempts to use the file B<value> in the "serverinfo" extension using the +function SSL_CTX_use_serverinfo_file. + +=item B<DHParameters> + +Attempts to use the file B<value> as the set of temporary DH parameters for +the appropriate context. This option is only supported if certificate +operations are permitted. + +=item B<NoRenegotiation> + +Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting +B<SSL_OP_NO_RENEGOTIATION>. + +=item B<SignatureAlgorithms> + +This sets the supported signature algorithms for TLS v1.2. For clients this +value is used directly for the supported signature algorithms extension. For +servers it is used to determine which signature algorithms to support. + +The B<value> argument should be a colon separated list of signature algorithms +in order of decreasing preference of the form B<algorithm+hash>. B<algorithm> +is one of B<RSA>, B<DSA> or B<ECDSA> and B<hash> is a supported algorithm +OID short name such as B<SHA1>, B<SHA224>, B<SHA256>, B<SHA384> of B<SHA512>. +Note: algorithm and hash names are case sensitive. + +If this option is not set then all signature algorithms supported by the +OpenSSL library are permissible. + +=item B<ClientSignatureAlgorithms> + +This sets the supported signature algorithms associated with client +authentication for TLS v1.2. For servers the value is used in the supported +signature algorithms field of a certificate request. For clients it is +used to determine which signature algorithm to with the client certificate. + +The syntax of B<value> is identical to B<SignatureAlgorithms>. If not set then +the value set for B<SignatureAlgorithms> will be used instead. + +=item B<Curves> + +This sets the supported elliptic curves. For clients the curves are +sent using the supported curves extension. For servers it is used +to determine which curve to use. This setting affects curves used for both +signatures and key exchange, if applicable. + +The B<value> argument is a colon separated list of curves. The curve can be +either the B<NIST> name (e.g. B<P-256>) or an OpenSSL OID name (e.g +B<prime256v1>). Curve names are case sensitive. + +=item B<MinProtocol> + +This sets the minimum supported SSL, TLS or DTLS version. + +Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, +B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>. +The value B<None> will disable the limit. + +=item B<MaxProtocol> + +This sets the maximum supported SSL, TLS or DTLS version. + +Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, +B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>. +The value B<None> will disable the limit. + +=item B<Protocol> + +This can be used to enable or disable certain versions of the SSL, +TLS or DTLS protocol. + +The B<value> argument is a comma separated list of supported protocols +to enable or disable. +If a protocol is preceded by B<-> that version is disabled. + +All protocol versions are enabled by default. +You need to disable at least one protocol version for this setting have any +effect. +Only enabling some protocol versions does not disable the other protocol +versions. + +Currently supported protocol values are B<SSLv3>, B<TLSv1>, B<TLSv1.1>, +B<TLSv1.2>, B<DTLSv1> and B<DTLSv1.2>. +The special value B<ALL> refers to all supported versions. + +This can't enable protocols that are disabled using B<MinProtocol> +or B<MaxProtocol>, but can disable protocols that are still allowed +by them. + +The B<Protocol> command is fragile and deprecated; do not use it. +Use B<MinProtocol> and B<MaxProtocol> instead. +If you do use B<Protocol>, make sure that the resulting range of enabled +protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make +sure to also leave TLS 1.1 enabled. + +=item B<Options> + +The B<value> argument is a comma separated list of various flags to set. +If a flag string is preceded B<-> it is disabled. +See the L<SSL_CTX_set_options(3)> function for more details of +individual options. + +Each option is listed below. Where an operation is enabled by default +the B<-flag> syntax is needed to disable it. + +B<SessionTicket>: session ticket support, enabled by default. Inverse of +B<SSL_OP_NO_TICKET>: that is B<-SessionTicket> is the same as setting +B<SSL_OP_NO_TICKET>. + +B<Compression>: SSL/TLS compression support, enabled by default. Inverse +of B<SSL_OP_NO_COMPRESSION>. + +B<EmptyFragments>: use empty fragments as a countermeasure against a +SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It +is set by default. Inverse of B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS>. + +B<Bugs>: enable various bug workarounds. Same as B<SSL_OP_ALL>. + +B<DHSingle>: enable single use DH keys, set by default. Inverse of +B<SSL_OP_DH_SINGLE>. Only used by servers. + +B<ECDHSingle> enable single use ECDH keys, set by default. Inverse of +B<SSL_OP_ECDH_SINGLE>. Only used by servers. + +B<ServerPreference> use server and not client preference order when +determining which cipher suite, signature algorithm or elliptic curve +to use for an incoming connection. Equivalent to +B<SSL_OP_CIPHER_SERVER_PREFERENCE>. Only used by servers. + +B<NoResumptionOnRenegotiation> set +B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers. + +B<UnsafeLegacyRenegotiation> permits the use of unsafe legacy renegotiation. +Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>. + +B<UnsafeLegacyServerConnect> permits the use of unsafe legacy renegotiation +for OpenSSL clients only. Equivalent to B<SSL_OP_LEGACY_SERVER_CONNECT>. +Set by default. + +=item B<VerifyMode> + +The B<value> argument is a comma separated list of flags to set. + +B<Peer> enables peer verification: for clients only. + +B<Request> requests but does not require a certificate from the client. +Servers only. + +B<Require> requests and requires a certificate from the client: an error +occurs if the client does not present a certificate. Servers only. + +B<Once> requests a certificate from a client only on the initial connection: +not when renegotiating. Servers only. + +=item B<ClientCAFile>, B<ClientCAPath> + +A file or directory of certificates in PEM format whose names are used as the +set of acceptable names for client CAs. Servers only. This option is only +supported if certificate operations are permitted. + +=back + +=head1 SUPPORTED COMMAND TYPES + +The function SSL_CONF_cmd_value_type() currently returns one of the following +types: + +=over 4 + +=item B<SSL_CONF_TYPE_UNKNOWN> + +The B<cmd> string is unrecognised, this return value can be use to flag +syntax errors. + +=item B<SSL_CONF_TYPE_STRING> + +The value is a string without any specific structure. + +=item B<SSL_CONF_TYPE_FILE> + +The value is a file name. + +=item B<SSL_CONF_TYPE_DIR> + +The value is a directory name. + +=item B<SSL_CONF_TYPE_NONE> + +The value string is not used e.g. a command line option which doesn't take an +argument. + +=back + +=head1 NOTES + +The order of operations is significant. This can be used to set either defaults +or values which cannot be overridden. For example if an application calls: + + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); + SSL_CONF_cmd(ctx, userparam, uservalue); + +it will disable SSLv3 support by default but the user can override it. If +however the call sequence is: + + SSL_CONF_cmd(ctx, userparam, uservalue); + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); + +SSLv3 is B<always> disabled and attempt to override this by the user are +ignored. + +By checking the return code of SSL_CTX_cmd() it is possible to query if a +given B<cmd> is recognised, this is useful if SSL_CTX_cmd() values are +mixed with additional application specific operations. + +For example an application might call SSL_CTX_cmd() and if it returns +-2 (unrecognised command) continue with processing of application specific +commands. + +Applications can also use SSL_CTX_cmd() to process command lines though the +utility function SSL_CTX_cmd_argv() is normally used instead. One way +to do this is to set the prefix to an appropriate value using +SSL_CONF_CTX_set1_prefix(), pass the current argument to B<cmd> and the +following argument to B<value> (which may be NULL). + +In this case if the return value is positive then it is used to skip that +number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is +returned then B<cmd> is not recognised and application specific arguments +can be checked instead. If -3 is returned a required argument is missing +and an error is indicated. If 0 is returned some other error occurred and +this can be reported back to the user. + +The function SSL_CONF_cmd_value_type() can be used by applications to +check for the existence of a command or to perform additional syntax +checking or translation of the command value. For example if the return +value is B<SSL_CONF_TYPE_FILE> an application could translate a relative +pathname to an absolute pathname. + +=head1 EXAMPLES + +Set supported signature algorithms: + + SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256"); + +There are various ways to select the supported protocols. + +This set the minimum protocol version to TLSv1, and so disables SSLv3. +This is the recommended way to disable protocols. + + SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1"); + +The following also disables SSLv3: + + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); + +The following will first enable all protocols, and then disable +SSLv3. +If no protocol versions were disabled before this has the same effect as +"-SSLv3", but if some versions were disables this will re-enable them before +disabling SSLv3. + + SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3"); + +Only enable TLSv1.2: + + SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2"); + SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2"); + +This also only enables TLSv1.2: + + SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2"); + +Disable TLS session tickets: + + SSL_CONF_cmd(ctx, "Options", "-SessionTicket"); + +Enable compression: + + SSL_CONF_cmd(ctx, "Options", "Compression"); + +Set supported curves to P-256, P-384: + + SSL_CONF_cmd(ctx, "Curves", "P-256:P-384"); + +Set automatic support for any elliptic curve for key exchange: + + SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic"); + +=head1 RETURN VALUES + +SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is +B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it +returns the number of arguments processed. This is useful when processing +command lines. + +A return value of -2 means B<cmd> is not recognised. + +A return value of -3 means B<cmd> is recognised and the command requires a +value but B<value> is NULL. + +A return code of 0 indicates that both B<cmd> and B<value> are valid but an +error occurred attempting to perform the operation: for example due to an +error in the syntax of B<value> in this case the error queue may provide +additional information. + +SSL_CONF_finish() returns 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<SSL_CONF_CTX_new(3)>, +L<SSL_CONF_CTX_set_flags(3)>, +L<SSL_CONF_CTX_set1_prefix(3)>, +L<SSL_CONF_CTX_set_ssl_ctx(3)>, +L<SSL_CONF_cmd_argv(3)>, +L<SSL_CTX_set_options(3)> + +=head1 HISTORY + +SSL_CONF_cmd() was first added to OpenSSL 1.0.2 + +B<SSL_OP_NO_SSL2> doesn't have effect since 1.1.0, but the macro is retained +for backwards compatibility. + +B<SSL_CONF_TYPE_NONE> was first added to OpenSSL 1.1.0. In earlier versions of +OpenSSL passing a command which didn't take an argument would return +B<SSL_CONF_TYPE_UNKNOWN>. + +B<MinProtocol> and B<MaxProtocol> where added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2012-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod new file mode 100644 index 0000000..15529a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +SSL_CONF_cmd_argv - SSL configuration command line processing + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CONF_cmd_argv(SSL_CONF_CTX *cctx, int *pargc, char ***pargv); + +=head1 DESCRIPTION + +The function SSL_CONF_cmd_argv() processes at most two command line +arguments from B<pargv> and B<pargc>. The values of B<pargv> and B<pargc> +are updated to reflect the number of command options processed. The B<pargc> +argument can be set to B<NULL> is it is not used. + +=head1 RETURN VALUES + +SSL_CONF_cmd_argv() returns the number of command arguments processed: 0, 1, 2 +or a negative error code. + +If -2 is returned then an argument for a command is missing. + +If -1 is returned the command is recognised but couldn't be processed due +to an error: for example a syntax error in the argument. + +=head1 SEE ALSO + +L<SSL_CONF_CTX_new(3)>, +L<SSL_CONF_CTX_set_flags(3)>, +L<SSL_CONF_CTX_set1_prefix(3)>, +L<SSL_CONF_CTX_set_ssl_ctx(3)>, +L<SSL_CONF_cmd(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod new file mode 100644 index 0000000..1f0418b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod @@ -0,0 +1,158 @@ +=pod + +=head1 NAME + +SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert, +SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs, +SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert, +SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain, +SSL_build_cert_chain, SSL_CTX_select_current_cert, +SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra +chain certificate processing + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); + int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); + int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509); + int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509); + int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk); + int SSL_CTX_clear_chain_certs(SSL_CTX *ctx); + + int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk); + int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk); + int SSL_add0_chain_cert(SSL *ssl, X509 *x509); + int SSL_add1_chain_cert(SSL *ssl, X509 *x509); + int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk); + int SSL_clear_chain_certs(SSL *ssl); + + int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags); + int SSL_build_cert_chain(SSL *ssl, flags); + + int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509); + int SSL_select_current_cert(SSL *ssl, X509 *x509); + int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op); + int SSL_set_current_cert(SSL *ssl, long op); + +=head1 DESCRIPTION + +SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain +associated with the current certificate of B<ctx> to B<sk>. + +SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single +certificate B<x509> to the chain associated with the current certificate of +B<ctx>. + +SSL_CTX_get0_chain_certs() retrieves the chain associated with the current +certificate of B<ctx>. + +SSL_CTX_clear_chain_certs() clears any existing chain associated with the +current certificate of B<ctx>. (This is implemented by calling +SSL_CTX_set0_chain() with B<sk> set to B<NULL>). + +SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx> normally +this uses the chain store or the verify store if the chain store is not set. +If the function is successful the built chain will replace any existing chain. +The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use +existing chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT> +to omit the root CA from the built chain, B<SSL_BUILD_CHAIN_FLAG_CHECK> to +use all existing chain certificates only to build the chain (effectively +sanity checking and rearranging them if necessary), the flag +B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification: +if flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors +are cleared from the error queue. + +Each of these functions operates on the I<current> end entity +(i.e. server or client) certificate. This is the last certificate loaded or +selected on the corresponding B<ctx> structure. + +SSL_CTX_select_current_cert() selects B<x509> as the current end entity +certificate, but only if B<x509> has already been loaded into B<ctx> using a +function such as SSL_CTX_use_certificate(). + +SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(), +SSL_add1_chain_cert(), SSL_get0_chain_certs(), SSL_clear_chain_certs(), +SSL_build_cert_chain(), SSL_select_current_cert() and SSL_set_current_cert() +are similar except they apply to SSL structure B<ssl>. + +SSL_CTX_set_current_cert() changes the current certificate to a value based +on the B<op> argument. Currently B<op> can be B<SSL_CERT_SET_FIRST> to use +the first valid certificate or B<SSL_CERT_SET_NEXT> to set the next valid +certificate after the current certificate. These two operations can be +used to iterate over all certificates in an B<SSL_CTX> structure. + +SSL_set_current_cert() also supports the option B<SSL_CERT_SET_SERVER>. +If B<ssl> is a server and has sent a certificate to a connected client +this option sets that certificate to the current certificate and returns 1. +If the negotiated ciphersuite is anonymous (and thus no certificate will +be sent) 2 is returned and the current certificate is unchanged. If B<ssl> +is not a server or a certificate has not been sent 0 is returned and +the current certificate is unchanged. + +All these functions are implemented as macros. Those containing a B<1> +increment the reference count of the supplied certificate or chain so it must +be freed at some point after the operation. Those containing a B<0> do +not increment reference counts and the supplied certificate or chain +B<MUST NOT> be freed after the operation. + +=head1 NOTES + +The chains associate with an SSL_CTX structure are copied to any SSL +structures when SSL_new() is called. SSL structures will not be affected +by any chains subsequently changed in the parent SSL_CTX. + +One chain can be set for each key type supported by a server. So, for example, +an RSA and a DSA certificate can (and often will) have different chains. + +The functions SSL_CTX_build_cert_chain() and SSL_build_cert_chain() can +be used to check application configuration and to ensure any necessary +subordinate CAs are sent in the correct order. Misconfigured applications +sending incorrect certificate chains often cause problems with peers. + +For example an application can add any set of certificates using +SSL_CTX_use_certificate_chain_file() then call SSL_CTX_build_cert_chain() +with the option B<SSL_BUILD_CHAIN_FLAG_CHECK> to check and reorder them. + +Applications can issue non fatal warnings when checking chains by setting +the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS> and checking the return +value. + +Calling SSL_CTX_build_cert_chain() or SSL_build_cert_chain() is more +efficient than the automatic chain building as it is only performed once. +Automatic chain building is performed on each new session. + +If any certificates are added using these functions no certificates added +using SSL_CTX_add_extra_chain_cert() will be used. + +=head1 RETURN VALUES + +SSL_set_current_cert() with B<SSL_CERT_SET_SERVER> return 1 for success, 2 if +no server certificate is used because the ciphersuites is anonymous and 0 +for failure. + +SSL_CTX_build_cert_chain() and SSL_build_cert_chain() return 1 for success +and 0 for failure. If the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> and +a verification error occurs then 2 is returned. + +All other functions return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<SSL_CTX_add_extra_chain_cert(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod new file mode 100644 index 0000000..e2783de --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +SSL_CTX_add_extra_chain_cert, SSL_CTX_clear_extra_chain_certs - add or clear +extra chain certificates + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509); + long SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the extra chain +certificates associated with B<ctx>. Several certificates can be added one +after another. + +SSL_CTX_clear_extra_chain_certs() clears all extra chain certificates +associated with B<ctx>. + +These functions are implemented as macros. + +=head1 NOTES + +When sending a certificate chain, extra chain certificates are sent in order +following the end entity certificate. + +If no chain is specified, 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)>. + +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. For more flexibility functions such as SSL_add1_chain_cert() should +be used instead. + +=head1 RETURN VALUES + +SSL_CTX_add_extra_chain_cert() and SSL_CTX_clear_extra_chain_certs() return +1 on success and 0 for failure. Check out the error stack to find out the +reason for failure. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_use_certificate(3)>, +L<SSL_CTX_set_client_cert_cb(3)>, +L<SSL_CTX_load_verify_locations(3)> +L<SSL_CTX_set0_chain(3)> +L<SSL_CTX_set1_chain(3)> +L<SSL_CTX_add0_chain_cert(3)> +L<SSL_CTX_add1_chain_cert(3)> +L<SSL_set0_chain(3)> +L<SSL_set1_chain(3)> +L<SSL_add0_chain_cert(3)> +L<SSL_add1_chain_cert(3)> +L<SSL_CTX_build_cert_chain(3)> +L<SSL_build_cert_chain(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod new file mode 100644 index 0000000..dbdd9f0 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, SSL_remove_session - manipulate session cache + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c); + int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c); + + int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c); + int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c); + +=head1 DESCRIPTION + +SSL_CTX_add_session() adds the session B<c> to the context B<ctx>. The +reference count for session B<c> is incremented by 1. If a session with +the same session id already exists, the old session is removed by calling +L<SSL_SESSION_free(3)>. + +SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>. +L<SSL_SESSION_free(3)> is called once for B<c>. + +SSL_add_session() and SSL_remove_session() are synonyms for their +SSL_CTX_*() counterparts. + +=head1 NOTES + +When adding a new session to the internal session cache, it is examined +whether a session with the same session id already exists. In this case +it is assumed that both sessions are identical. If the same session is +stored in a different SSL_SESSION object, The old session is +removed and replaced by the new session. If the session is actually +identical (the SSL_SESSION object is identical), SSL_CTX_add_session() +is a no-op, and the return value is 0. + +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 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. + + +=head1 RETURN VALUES + +The following values are returned by all functions: + +=over 4 + +=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 Z<>1 + + The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_free(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod new file mode 100644 index 0000000..ec744ad --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_config(SSL_CTX *ctx, const char *name); + int SSL_config(SSL *s, const char *name); + +=head1 DESCRIPTION + +The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or +B<SSL> structure using the configuration B<name>. + +=head1 NOTES + +By calling SSL_CTX_config() or SSL_config() an application can perform many +complex tasks based on the contents of the configuration file: greatly +simplifying application configuration code. A degree of future proofing +can also be achieved: an application can support configuration features +in newer versions of OpenSSL automatically. + +A configuration file must have been previously loaded, for example using +CONF_modules_load_file(). See L<config(3)> for details of the configuration +file syntax. + +=head1 RETURN VALUES + +SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error +occurred. + +=head1 EXAMPLE + +If the file "config.cnf" contains the following: + + testapp = test_sect + + [test_sect] + # list of configuration modules + + ssl_conf = ssl_sect + + [ssl_sect] + + server = server_section + + [server_section] + + RSA.Certificate = server-rsa.pem + ECDSA.Certificate = server-ecdsa.pem + Ciphers = ALL:!RC4 + +An application could call: + + if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) { + fprintf(stderr, "Error processing config file\n"); + goto err; + } + + ctx = SSL_CTX_new(TLS_server_method()); + + if (SSL_CTX_config(ctx, "server") == 0) { + fprintf(stderr, "Error configuring server.\n"); + goto err; + } + +In this example two certificates and the cipher list are configured without +the need for any additional application code. + +=head1 SEE ALSO + +L<config(3)>, +L<SSL_CONF_cmd(3)>, +L<CONF_modules_load_file(3)> + +=head1 HISTORY + +SSL_CTX_config() and SSL_config() were first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod new file mode 100644 index 0000000..e8386a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + +SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal handling functions for SSL_CTX and SSL objects + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg); + long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)()); + + long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg); + long SSL_callback_ctrl(SSL *, int cmd, void (*fp)()); + +=head1 DESCRIPTION + +The SSL_*_ctrl() family of functions is used to manipulate settings of +the SSL_CTX and SSL objects. Depending on the command B<cmd> the arguments +B<larg>, B<parg>, or B<fp> are evaluated. These functions should never +be called directly. All functionalities needed are made available via +other functions or macros. + +=head1 RETURN VALUES + +The return values of the SSL*_ctrl() functions depend on the command +supplied via the B<cmd> parameter. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod new file mode 100644 index 0000000..cdb6d1b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod @@ -0,0 +1,384 @@ +=pod + +=head1 NAME + +SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable, +SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa, +SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags, +SSL_dane_set_flags, SSL_dane_clear_flags +- enable DANE TLS authentication of the remote TLS server in the local +TLS client + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_dane_enable(SSL_CTX *ctx); + int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md, + uint8_t mtype, uint8_t ord); + int SSL_dane_enable(SSL *s, const char *basedomain); + int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector, + uint8_t mtype, unsigned char *data, size_t dlen); + int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki); + int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector, + uint8_t *mtype, unsigned const char **data, + size_t *dlen); + unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags); + unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags); + unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags); + unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags); + +=head1 DESCRIPTION + +These functions implement support for DANE TLSA (RFC6698 and RFC7671) +peer authentication. + +SSL_CTX_dane_enable() must be called first to initialize the shared state +required for DANE support. +Individual connections associated with the context can then enable +per-connection DANE support as appropriate. +DANE authentication is implemented in the L<X509_verify_cert(3)> function, and +applications that override L<X509_verify_cert(3)> via +L<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer +chain in whatever manner they see fit. + +SSL_CTX_dane_mtype_set() may then be called zero or more times to adjust the +supported digest algorithms. +This must be done before any SSL handles are created for the context. + +The B<mtype> argument specifies a DANE TLSA matching type and the B<md> +argument specifies the associated digest algorithm handle. +The B<ord> argument specifies a strength ordinal. +Algorithms with a larger strength ordinal are considered more secure. +Strength ordinals are used to implement RFC7671 digest algorithm agility. +Specifying a B<NULL> digest algorithm for a matching type disables +support for that matching type. +Matching type Full(0) cannot be modified or disabled. + +By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions +of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()> +with a strength ordinal of C<1> and matching type C<SHA2-512(2)> +is mapped to C<EVP_sha512()> with a strength ordinal of C<2>. + +SSL_dane_enable() must be called before the SSL handshake is initiated with +L<SSL_connect(3)> if (and only if) you want to enable DANE for that connection. +(The connection must be associated with a DANE-enabled SSL context). +The B<basedomain> argument specifies the RFC7671 TLSA base domain, +which will be the primary peer reference identifier for certificate +name checks. +Additional server names can be specified via L<SSL_add1_host(3)>. +The B<basedomain> is used as the default SNI hint if none has yet been +specified via L<SSL_set_tlsext_host_name(3)>. + +SSL_dane_tlsa_add() may then be called one or more times, to load each of the +TLSA records that apply to the remote TLS peer. +(This too must be done prior to the beginning of the SSL handshake). +The arguments specify the fields of the TLSA record. +The B<data> field is provided in binary (wire RDATA) form, not the hexadecimal +ASCII presentation form, with an explicit length passed via B<dlen>. +The library takes a copy of the B<data> buffer contents and the caller may +free the original B<data> buffer when convenient. +A return value of 0 indicates that "unusable" TLSA records (with invalid or +unsupported parameters) were provided. +A negative return value indicates an internal error in processing the record. + +The caller is expected to check the return value of each SSL_dane_tlsa_add() +call and take appropriate action if none are usable or an internal error +is encountered in processing some records. + +If no TLSA records are added successfully, DANE authentication is not enabled, +and authentication will be based on any configured traditional trust-anchors; +authentication success in this case does not mean that the peer was +DANE-authenticated. + +SSL_get0_dane_authority() can be used to get more detailed information about +the matched DANE trust-anchor after successful connection completion. +The return value is negative if DANE verification failed (or was not enabled), +0 if an EE TLSA record directly matched the leaf certificate, or a positive +number indicating the depth at which a TA record matched an issuer certificate. +The complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>. +The return value is an index into this verified chain, rather than the list of +certificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>. + +If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain +certificate, a pointer to the matching certificate is returned via B<mcert>. +The returned address is a short-term internal reference to the certificate and +must not be freed by the application. +Applications that want to retain access to the certificate can call +L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via +L<X509_free(3)> once no longer needed. + +If no TLSA records directly matched any elements of the certificate chain, but +a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an +element of the chain, then that key is returned via B<mspki> argument (if not +NULL). +In this case the return value is the depth of the top-most element of the +validated certificate chain. +As with B<mcert> this is a short-term internal reference, and +L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and +release long-term references respectively. + +SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that +matched the peer certificate chain. +The return value indicates the match depth or failure to match just as with +SSL_get0_dane_authority(). +When the return value is non-negative, the storage pointed to by the B<usage>, +B<selector>, B<mtype> and B<data> parameters is updated to the corresponding +TLSA record fields. +The B<data> field is in binary wire form, and is therefore not NUL-terminated, +its length is returned via the B<dlen> parameter. +If any of these parameters is NULL, the corresponding field is not returned. +The B<data> parameter is set to a short-term internal-copy of the associated +data field and must not be freed by the application. +Applications that need long-term access to this field need to copy the content. + +SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable +optional DANE verification features. +SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable +the same features. +The B<flags> argument is a bitmask of the features to enable or disable. +The B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle +associated with that context at the time the handle is created. +Subsequent changes in the context's B<flags> have no effect on the B<flags> set +for the handle. + +At present, the only available option is B<DANE_FLAG_NO_DANE_EE_NAMECHECKS> +which can be used to disable server name checks when authenticating via +DANE-EE(3) TLSA records. +For some applications, primarily web browsers, it is not safe to disable name +checks due to "unknown key share" attacks, in which a malicious server can +convince a client that a connection to a victim server is instead a secure +connection to the malicious server. +The malicious server may then be able to violate cross-origin scripting +restrictions. +Thus, despite the text of RFC7671, name checks are by default enabled for +DANE-EE(3) TLSA records, and can be disabled in applications where it is safe +to do so. +In particular, SMTP and XMPP clients should set this option as SRV and MX +records already make it possible for a remote domain to redirect client +connections to any server of its choice, and in any case SMTP and XMPP clients +do not execute scripts downloaded from remote servers. + +=head1 RETURN VALUES + +The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(), +SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success. +Negative return values indicate resource problems (out of memory, etc.) in the +SSL library, while a return value of B<0> indicates incorrect usage or invalid +input, such as an unsupported TLSA record certificate usage, selector or +matching type. +Invalid input also includes malformed data, either a digest length that does +not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form) +certificate or a public key that fails to parse. + +The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a +negative value when DANE authentication failed or was not enabled, a +non-negative value indicates the chain depth at which the TLSA record matched a +chain certificate, or the depth of the top-most certificate, when the TLSA +record is a full public key that is its signer. + +The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(), +SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect +before they were called. + +=head1 EXAMPLE + +Suppose "smtp.example.com" is the MX host of the domain "example.com", and has +DNSSEC-validated TLSA records. +The calls below will perform DANE authentication and arrange to match either +the MX hostname or the destination domain name in the SMTP server certificate. +Wildcards are supported, but must match the entire label. +The actual name matched in the certificate (which might be a wildcard) is +retrieved, and must be copied by the application if it is to be retained beyond +the lifetime of the SSL connection. + + SSL_CTX *ctx; + SSL *ssl; + int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL; + int num_usable = 0; + const char *nexthop_domain = "example.com"; + const char *dane_tlsa_domain = "smtp.example.com"; + uint8_t usage, selector, mtype; + + if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) + /* handle error */ + if (SSL_CTX_dane_enable(ctx) <= 0) + /* handle error */ + + if ((ssl = SSL_new(ctx)) == NULL) + /* handle error */ + + if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) + /* handle error */ + + /* + * For many applications it is safe to skip DANE-EE(3) namechecks. Do not + * disable the checks unless "unknown key share" attacks pose no risk for + * your application. + */ + SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS); + + if (!SSL_add1_host(ssl, nexthop_domain)) + /* handle error */ + SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); + + for (... each TLSA record ...) { + unsigned char *data; + size_t len; + int ret; + + /* set usage, selector, mtype, data, len */ + + /* + * Opportunistic DANE TLS clients support only DANE-TA(2) or DANE-EE(3). + * They treat all other certificate usages, and in particular PKIX-TA(0) + * and PKIX-EE(1), as unusable. + */ + switch (usage) { + default: + case 0: /* PKIX-TA(0) */ + case 1: /* PKIX-EE(1) */ + continue; + case 2: /* DANE-TA(2) */ + case 3: /* DANE-EE(3) */ + break; + } + + ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len); + /* free data as appropriate */ + + if (ret < 0) + /* handle SSL library internal error */ + else if (ret == 0) + /* handle unusable TLSA record */ + else + ++num_usable; + } + + /* + * At this point, the verification mode is still the default SSL_VERIFY_NONE. + * Opportunistic DANE clients use unauthenticated TLS when all TLSA records + * are unusable, so continue the handshake even if authentication fails. + */ + if (num_usable == 0) { + /* Log all records unusable? */ + + /* Optionally set verify_cb to a suitable non-NULL callback. */ + SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb); + } else { + /* At least one usable record. We expect to verify the peer */ + + /* Optionally set verify_cb to a suitable non-NULL callback. */ + + /* + * Below we elect to fail the handshake when peer verification fails. + * Alternatively, use the permissive SSL_VERIFY_NONE verification mode, + * complete the handshake, check the verification status, and if not + * verified disconnect gracefully at the application layer, especially if + * application protocol supports informing the server that authentication + * failed. + */ + SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb); + } + + /* + * Load any saved session for resumption, making sure that the previous + * session applied the same security and authentication requirements that + * would be expected of a fresh connection. + */ + + /* Perform SSL_connect() handshake and handle errors here */ + + if (SSL_session_reused(ssl)) { + if (SSL_get_verify_result(ssl) == X509_V_OK) { + /* + * Resumed session was originally verified, this connection is + * authenticated. + */ + } else { + /* + * Resumed session was not originally verified, this connection is not + * authenticated. + */ + } + } else if (SSL_get_verify_result(ssl) == X509_V_OK) { + const char *peername = SSL_get0_peername(ssl); + EVP_PKEY *mspki = NULL; + + int depth = SSL_get0_dane_authority(ssl, NULL, &mspki); + if (depth >= 0) { + (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL); + printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype, + (mspki != NULL) ? "TA public key verified certificate" : + depth ? "matched TA certificate" : "matched EE certificate", + depth); + } + if (peername != NULL) { + /* Name checks were in scope and matched the peername */ + printf("Verified peername: %s\n", peername); + } + } else { + /* + * Not authenticated, presumably all TLSA rrs unusable, but possibly a + * callback suppressed connection termination despite the presence of + * usable TLSA RRs none of which matched. Do whatever is appropriate for + * fresh unauthenticated connections. + */ + } + +=head1 NOTES + +It is expected that the majority of clients employing DANE TLS will be doing +"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435. +That is, they will use DANE authentication when DNSSEC-validated TLSA records +are published for a given peer, and otherwise will use unauthenticated TLS or +even cleartext. + +Such applications should generally treat any TLSA records published by the peer +with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include +them among the TLSA records used to authenticate peer connections. +In addition, some TLSA records with supported usages may be "unusable" as a +result of invalid or unsupported parameters. + +When a peer has TLSA records, but none are "usable", an opportunistic +application must avoid cleartext, but cannot authenticate the peer, +and so should generally proceed with an unauthenticated connection. +Opportunistic applications need to note the return value of each +call to SSL_dane_tlsa_add(), and if all return 0 (due to invalid +or unsupported parameters) disable peer authentication by calling +L<SSL_set_verify(3)> with B<mode> equal to B<SSL_VERIFY_NONE>. + +=head1 SEE ALSO + +L<SSL_new(3)>, +L<SSL_add1_host(3)>, +L<SSL_set_hostflags(3)>, +L<SSL_set_tlsext_host_name(3)>, +L<SSL_set_verify(3)>, +L<SSL_CTX_set_cert_verify_callback(3)>, +L<SSL_get0_verified_chain(3)>, +L<SSL_get_peer_cert_chain(3)>, +L<SSL_get_verify_result(3)>, +L<SSL_connect(3)>, +L<SSL_get0_peername(3)>, +L<X509_verify_cert(3)>, +L<X509_up_ref(3)>, +L<X509_free(3)>, +L<EVP_get_digestbyname(3)>, +L<EVP_PKEY_up_ref(3)>, +L<EVP_PKEY_free(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod new file mode 100644 index 0000000..7639451 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm); + void SSL_flush_sessions(SSL_CTX *ctx, long tm); + +=head1 DESCRIPTION + +SSL_CTX_flush_sessions() causes a run through the session cache of +B<ctx> to remove sessions expired at time B<tm>. + +SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions(). + +=head1 NOTES + +If enabled, the internal session cache will collect all sessions established +up to the specified maximum number (see SSL_CTX_sess_set_cache_size()). +As sessions will not be reused ones they are expired, they should be +removed from the cache to save resources. This can either be done + automatically whenever 255 new sessions were established (see +L<SSL_CTX_set_session_cache_mode(3)>) +or manually by calling SSL_CTX_flush_sessions(). + +The parameter B<tm> specifies the time which should be used for the +expiration test, in most cases the actual time given by time(0) +will be used. + +SSL_CTX_flush_sessions() will only check sessions stored in the internal +cache. When a session is found and removed, the remove_session_cb is however +called to synchronize with the external cache (see +L<SSL_CTX_sess_set_get_cb(3)>). + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_set_timeout(3)>, +L<SSL_CTX_sess_set_get_cb(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod new file mode 100644 index 0000000..e5cc1aa --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +SSL_CTX_free - free an allocated SSL_CTX object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_free(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_free() decrements the reference count of B<ctx>, and removes the +SSL_CTX object pointed to by B<ctx> and frees up the allocated memory if the reference count has reached 0. + +It also calls the free()ing procedures for indirectly affected items, if +applicable: the session cache, the list of ciphers, the list of Client CAs, +the certificates and keys. + +If B<ctx> is NULL nothing is done. + +=head1 WARNINGS + +If a session-remove callback is set (SSL_CTX_sess_set_remove_cb()), this +callback will be called for each session being freed from B<ctx>'s +session cache. This implies, that all corresponding sessions from an +external session cache are removed as well. If this is not desired, the user +should explicitly unset the callback by calling +SSL_CTX_sess_set_remove_cb(B<ctx>, NULL) prior to calling SSL_CTX_free(). + +=head1 RETURN VALUES + +SSL_CTX_free() does not provide diagnostic information. + +=head1 SEE ALSO + +L<SSL_CTX_new(3)>, L<ssl(3)>, +L<SSL_CTX_sess_set_get_cb(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod new file mode 100644 index 0000000..6b93737 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param - +get and set verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx) + X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl) + int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm) + int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm) + +=head1 DESCRIPTION + +SSL_CTX_get0_param() and SSL_get0_param() retrieve an internal pointer to +the verification parameters for B<ctx> or B<ssl> respectively. The returned +pointer must not be freed by the calling application. + +SSL_CTX_set1_param() and SSL_set1_param() set the verification parameters +to B<vpm> for B<ctx> or B<ssl>. + +=head1 NOTES + +Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure +using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies +them to suit its needs: for example to add a hostname check. + +=head1 EXAMPLE + +Check hostname matches "www.foo.com" in peer certificate: + + X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl); + X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0); + +=head1 RETURN VALUES + +SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an +B<X509_VERIFY_PARAM> structure. + +SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0 +for failure. + +=head1 SEE ALSO + +L<X509_VERIFY_PARAM_set_flags(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod new file mode 100644 index 0000000..bd10034 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - get currently set verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_get_verify_mode(const SSL_CTX *ctx); + int SSL_get_verify_mode(const SSL *ssl); + int SSL_CTX_get_verify_depth(const SSL_CTX *ctx); + int SSL_get_verify_depth(const SSL *ssl); + int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int, X509_STORE_CTX *); + int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *); + +=head1 DESCRIPTION + +SSL_CTX_get_verify_mode() returns the verification mode currently set in +B<ctx>. + +SSL_get_verify_mode() returns the verification mode currently set in +B<ssl>. + +SSL_CTX_get_verify_depth() returns the verification depth limit currently set +in B<ctx>. If no limit has been explicitly set, -1 is returned and the +default value will be used. + +SSL_get_verify_depth() returns the verification depth limit currently set +in B<ssl>. If no limit has been explicitly set, -1 is returned and the +default value will be used. + +SSL_CTX_get_verify_callback() returns a function pointer to the verification +callback currently set in B<ctx>. If no callback was explicitly set, the +NULL pointer is returned and the default callback will be used. + +SSL_get_verify_callback() returns a function pointer to the verification +callback currently set in B<ssl>. If no callback was explicitly set, the +NULL pointer is returned and the default callback will be used. + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_CTX_set_verify(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod new file mode 100644 index 0000000..d9e9a06 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +SSL_CTX_has_client_custom_ext - check whether a handler exists for a particular +client extension type + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type); + +=head1 DESCRIPTION + +SSL_CTX_has_client_custom_ext() checks whether a handler has been set for a +client extension of type B<ext_type> using SSL_CTX_add_client_custom_ext(). + +=head1 RETURN VALUES + +Returns 1 if a handler has been set, 0 otherwise. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_add_client_custom_ext(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod new file mode 100644 index 0000000..59d11e0 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -0,0 +1,161 @@ +=pod + +=head1 NAME + +SSL_CTX_load_verify_locations, SSL_CTX_set_default_verify_paths, +SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file - set +default locations for trusted CA certificates + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, + const char *CApath); + + int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx); + + int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx); + + int SSL_CTX_set_default_verify_file(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at +which CA certificates for verification purposes are located. The certificates +available via B<CAfile> and B<CApath> are trusted. + +SSL_CTX_set_default_verify_paths() specifies that the default locations from +which CA certificates are loaded should be used. There is one default directory +and one default file. The default CA certificates directory is called "certs" in +the default OpenSSL directory. Alternatively the SSL_CERT_DIR environment +variable can be defined to override this location. The default CA certificates +file is called "cert.pem" in the default OpenSSL directory. Alternatively the +SSL_CERT_FILE environment variable can be defined to override this location. + +SSL_CTX_set_default_verify_dir() is similar to +SSL_CTX_set_default_verify_paths() except that just the default directory is +used. + +SSL_CTX_set_default_verify_file() is similar to +SSL_CTX_set_default_verify_paths() except that just the default file is +used. + +=head1 NOTES + +If B<CAfile> is not NULL, it points to a file of CA certificates in PEM +format. The file can contain several CA certificates identified by + + -----BEGIN CERTIFICATE----- + ... (CA certificate in base64 encoding) ... + -----END CERTIFICATE----- + +sequences. Before, between, and after the certificates text is allowed +which can be used e.g. for descriptions of the certificates. + +The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() +function. + +If B<CApath> is not NULL, it points to a directory containing CA certificates +in PEM format. The files each contain one CA certificate. The files are +looked up by the CA subject name hash value, which must hence be available. +If more than one CA certificate with the same name hash value exist, the +extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search +is performed in the ordering of the extension number, regardless of other +properties of the certificates. +Use the B<c_rehash> utility to create the necessary links. + +The certificates in B<CApath> are only looked up when required, e.g. when +building the certificate chain or when actually performing the verification +of a peer certificate. + +When looking up CA certificates, the OpenSSL library will first search the +certificates in B<CAfile>, then those in B<CApath>. Certificate matching +is done based on the subject name, the key identifier (if present), and the +serial number as taken from the certificate to be verified. If these data +do not match, the next certificate will be tried. If a first certificate +matching the parameters is found, the verification process will be performed; +no other certificates for the same parameters will be searched in case of +failure. + +In server mode, when requesting a client certificate, the server must send +the list of CAs of which it will accept client certificates. This list +is not influenced by the contents of B<CAfile> or B<CApath> and must +explicitly be set using the +L<SSL_CTX_set_client_CA_list(3)> +family of functions. + +When building its own certificate chain, an OpenSSL client/server will +try to fill in missing certificates from B<CAfile>/B<CApath>, if the +certificate chain was not explicitly specified (see +L<SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_use_certificate(3)>. + +=head1 WARNINGS + +If several CA certificates matching the name, key identifier, and serial +number condition are available, only the first one will be examined. This +may lead to unexpected results if the same CA certificate is available +with different expiration dates. If a "certificate expired" verification +error occurs, no other certificate will be searched. Make sure to not +have expired certificates mixed with valid ones. + +=head1 EXAMPLES + +Generate a CA certificate file with descriptive text from the CA certificates +ca1.pem ca2.pem ca3.pem: + + #!/bin/sh + rm CAfile.pem + for i in ca1.pem ca2.pem ca3.pem ; do + openssl x509 -in $i -text >> CAfile.pem + done + +Prepare the directory /some/where/certs containing several CA certificates +for use as B<CApath>: + + cd /some/where/certs + c_rehash . + +=head1 RETURN VALUES + +For SSL_CTX_load_verify_locations the following return values can occur: + +=over 4 + +=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 Z<>1 + +The operation succeeded. + +=back + +SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and +SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A +missing default location is still treated as a success. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)>, +L<SSL_get_client_CA_list(3)>, +L<SSL_CTX_use_certificate(3)>, +L<SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_set_cert_store(3)>, +L<SSL_CTX_set_client_CA_list(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod new file mode 100644 index 0000000..7b35bdd --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod @@ -0,0 +1,218 @@ +=pod + +=head1 NAME + +TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, +SSL_CTX_new, SSL_CTX_up_ref, SSLv3_method, SSLv3_server_method, +SSLv3_client_method, TLSv1_method, TLSv1_server_method, TLSv1_client_method, +TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, TLS_method, +TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, +SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method, +DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method, +DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method +- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled +functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); + int SSL_CTX_up_ref(SSL_CTX *ctx); + + const SSL_METHOD *TLS_method(void); + const SSL_METHOD *TLS_server_method(void); + const SSL_METHOD *TLS_client_method(void); + + const SSL_METHOD *SSLv23_method(void); + const SSL_METHOD *SSLv23_server_method(void); + const SSL_METHOD *SSLv23_client_method(void); + + #ifndef OPENSSL_NO_SSL3_METHOD + const SSL_METHOD *SSLv3_method(void); + const SSL_METHOD *SSLv3_server_method(void); + const SSL_METHOD *SSLv3_client_method(void); + #endif + + #ifndef OPENSSL_NO_TLS1_METHOD + const SSL_METHOD *TLSv1_method(void); + const SSL_METHOD *TLSv1_server_method(void); + const SSL_METHOD *TLSv1_client_method(void); + #endif + + #ifndef OPENSSL_NO_TLS1_1_METHOD + const SSL_METHOD *TLSv1_1_method(void); + const SSL_METHOD *TLSv1_1_server_method(void); + const SSL_METHOD *TLSv1_1_client_method(void); + #endif + + #ifndef OPENSSL_NO_TLS1_2_METHOD + const SSL_METHOD *TLSv1_2_method(void); + const SSL_METHOD *TLSv1_2_server_method(void); + const SSL_METHOD *TLSv1_2_client_method(void); + #endif + + const SSL_METHOD *DTLS_method(void); + const SSL_METHOD *DTLS_server_method(void); + const SSL_METHOD *DTLS_client_method(void); + + #ifndef OPENSSL_NO_DTLS1_METHOD + const SSL_METHOD *DTLSv1_method(void); + const SSL_METHOD *DTLSv1_server_method(void); + const SSL_METHOD *DTLSv1_client_method(void); + #endif + + #ifndef OPENSSL_NO_DTLS1_2_METHOD + const SSL_METHOD *DTLSv1_2_method(void); + const SSL_METHOD *DTLSv1_2_server_method(void); + const SSL_METHOD *DTLSv1_2_client_method(void); + #endif + +=head1 DESCRIPTION + +SSL_CTX_new() creates a new B<SSL_CTX> object as framework to +establish TLS/SSL or DTLS enabled connections. An B<SSL_CTX> object is +reference counted. Creating an B<SSL_CTX> object for the first time increments +the reference count. Freeing it (using SSL_CTX_free) decrements it. When the +reference count drops to zero, any memory or resources allocated to the +B<SSL_CTX> object are freed. SSL_CTX_up_ref() increments the reference count for +an existing B<SSL_CTX> structure. + +=head1 NOTES + +The SSL_CTX object uses B<method> as connection method. +The methods exist in a generic type (for client and server use), a server only +type, and a client only type. +B<method> can be of the following types: + +=over 4 + +=item TLS_method(), TLS_server_method(), TLS_client_method() + +These are the general-purpose I<version-flexible> SSL/TLS methods. +The actual protocol version used will be negotiated to the highest version +mutually supported by the client and the server. +The supported protocols are SSLv3, TLSv1, TLSv1.1 and TLSv1.2. +Applications should use these methods, and avoid the version-specific +methods described below. + +=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() + +Use of these functions is deprecated. They have been replaced with the above +TLS_method(), TLS_server_method() and TLS_client_method() respectively. New +code should use those functions instead. + +=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() + +A TLS/SSL connection established with these methods will only understand the +TLSv1.2 protocol. + +=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() + +A TLS/SSL connection established with these methods will only understand the +TLSv1.1 protocol. + +=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() + +A TLS/SSL connection established with these methods will only understand the +TLSv1 protocol. + +=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() + +A TLS/SSL connection established with these methods will only understand the +SSLv3 protocol. +The SSLv3 protocol is deprecated and should not be used. + +=item DTLS_method(), DTLS_server_method(), DTLS_client_method() + +These are the version-flexible DTLS methods. +Currently supported protocols are DTLS 1.0 and DTLS 1.2. + +=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() + +These are the version-specific methods for DTLSv1.2. + +=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() + +These are the version-specific methods for DTLSv1. + +=back + +SSL_CTX_new() initializes the list of ciphers, the session cache setting, the +callbacks, the keys and certificates and the options to their default values. + +TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), +DTLS_server_method() and DTLS_client_method() are the I<version-flexible> +methods. +All other methods only support one specific protocol version. +Use the I<version-flexible> methods instead of the version specific methods. + +If you want to limit the supported protocols for the version flexible +methods you can use L<SSL_CTX_set_min_proto_version(3)>, +L<SSL_set_min_proto_version(3)>, L<SSL_CTX_set_max_proto_version(3)> and +L<SSL_set_max_proto_version(3)> functions. +Using these functions it is possible to choose e.g. TLS_server_method() +and be able to negotiate with all possible clients, but to only +allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2. + +The list of protocols available can also be limited using the +B<SSL_OP_NO_SSLv3>, B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and +B<SSL_OP_NO_TLSv1_2> options of the L<SSL_CTX_set_options(3)> or +L<SSL_set_options(3)> functions, but this approach is not recommended. +Clients should avoid creating "holes" in the set of protocols they support. +When disabling a protocol, make sure that you also disable either all previous +or all subsequent protocol versions. +In clients, when a protocol version is disabled without disabling I<all> +previous protocol versions, the effect is to also disable all subsequent +protocol versions. + +The SSLv3 protocol is deprecated and should generally not be used. +Applications should typically use L<SSL_CTX_set_min_proto_version(3)> to set +the minimum protocol to at least B<TLS1_VERSION>. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The creation of a new SSL_CTX object failed. Check the error stack to find out +the reason. + +=item Pointer to an SSL_CTX object + +The return value points to an allocated SSL_CTX object. + +SSL_CTX_up_ref() returns 1 for success and 0 for failure. + +=back + +=head1 HISTORY + +Support for SSLv2 and the corresponding SSLv2_method(), +SSLv2_server_method() and SSLv2_client_method() functions where +removed in OpenSSL 1.1.0. + +SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() +were deprecated and the preferred TLS_method(), TLS_server_method() +and TLS_client_method() functions were introduced in OpenSSL 1.1.0. + +All version-specific methods were deprecated in OpenSSL 1.1.0. + +=head1 SEE ALSO + +L<SSL_CTX_set_options(3)>, L<SSL_CTX_free(3)>, L<SSL_accept(3)>, +L<SSL_CTX_set_min_proto_version(3)>, L<ssl(3)>, L<SSL_set_connect_state(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod new file mode 100644 index 0000000..049c04c --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, SSL_CTX_sess_cache_full - obtain session cache statistics + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_sess_number(SSL_CTX *ctx); + long SSL_CTX_sess_connect(SSL_CTX *ctx); + long SSL_CTX_sess_connect_good(SSL_CTX *ctx); + long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx); + long SSL_CTX_sess_accept(SSL_CTX *ctx); + long SSL_CTX_sess_accept_good(SSL_CTX *ctx); + long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx); + long SSL_CTX_sess_hits(SSL_CTX *ctx); + long SSL_CTX_sess_cb_hits(SSL_CTX *ctx); + long SSL_CTX_sess_misses(SSL_CTX *ctx); + long SSL_CTX_sess_timeouts(SSL_CTX *ctx); + long SSL_CTX_sess_cache_full(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sess_number() returns the current number of sessions in the internal +session cache. + +SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in +client mode. + +SSL_CTX_sess_connect_good() returns the number of successfully established +SSL/TLS sessions in client mode. + +SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations +in client mode. + +SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in +server mode. + +SSL_CTX_sess_accept_good() returns the number of successfully established +SSL/TLS sessions in server mode. + +SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations +in server mode. + +SSL_CTX_sess_hits() returns the number of successfully reused sessions. +In client mode a session set with L<SSL_set_session(3)> +successfully reused is counted as a hit. In server mode a session successfully +retrieved from internal or external cache is counted as a hit. + +SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions +from the external session cache in server mode. + +SSL_CTX_sess_misses() returns the number of sessions proposed by clients +that were not found in the internal session cache in server mode. + +SSL_CTX_sess_timeouts() returns the number of sessions proposed by clients +and either found in the internal or external session cache in server mode, + but that were invalid due to timeout. These sessions are not included in +the SSL_CTX_sess_hits() count. + +SSL_CTX_sess_cache_full() returns the number of sessions that were removed +because the maximum session cache size was exceeded. + +=head1 RETURN VALUES + +The functions return the values indicated in the DESCRIPTION section. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_set_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)> +L<SSL_CTX_sess_set_cache_size(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod new file mode 100644 index 0000000..5aef10b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session cache size + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t); + long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_cache_size() sets the size of the internal session cache +of context B<ctx> to B<t>. +This value is a hint and not an absolute; see the notes below. + +SSL_CTX_sess_get_cache_size() returns the currently valid session cache size. + +=head1 NOTES + +The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT, +currently 1024*20, so that up to 20000 sessions can be held. This size +can be modified using the SSL_CTX_sess_set_cache_size() call. A special +case is the size 0, which is used for unlimited size. + +If adding the session makes the cache exceed its size, then unused +sessions are dropped from the end of the cache. +Cache space may also be reclaimed by calling +L<SSL_CTX_flush_sessions(3)> to remove +expired sessions. + +If the size of the session cache is reduced and more sessions are already +in the session cache, old session will be removed at the next time a +session shall be added. This removal is not synchronized with the +expiration of sessions. + +=head1 RETURN VALUES + +SSL_CTX_sess_set_cache_size() returns the previously valid size. + +SSL_CTX_sess_get_cache_size() returns the currently valid size. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_sess_number(3)>, +L<SSL_CTX_flush_sessions(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod new file mode 100644 index 0000000..d2b0e04 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - provide callback functions for server side external session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, + int (*new_session_cb)(SSL *, SSL_SESSION *)); + void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, + void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); + void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, + SSL_SESSION (*get_session_cb)(SSL *, const unsigned char *, int, int *)); + + int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess); + void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, const unsigned char *data, int len, int *copy); + + int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); + void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); + SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, + int len, int *copy); + +=head1 DESCRIPTION + +SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically +called whenever a new session was negotiated. + +SSL_CTX_sess_set_remove_cb() sets the callback function, which is +automatically called whenever a session is removed by the SSL engine, +because it is considered faulty or the session has become obsolete because +of exceeding the timeout value. + +SSL_CTX_sess_set_get_cb() sets the callback function which is called, +whenever a SSL/TLS client proposed to resume a session but the session +could not be found in the internal session cache (see +L<SSL_CTX_set_session_cache_mode(3)>). +(SSL/TLS server only.) + +SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and +SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the +provided callback functions. If a callback function has not been set, +the NULL pointer is returned. + +=head1 NOTES + +In order to allow external session caching, synchronization with the internal +session cache is realized via callback functions. Inside these callback +functions, session can be saved to disk or put into a database using the +L<d2i_SSL_SESSION(3)> interface. + +The new_session_cb() is called, whenever a new session has been negotiated +and session caching is enabled (see +L<SSL_CTX_set_session_cache_mode(3)>). +The new_session_cb() is passed the B<ssl> connection and the ssl session +B<sess>. If the callback returns B<0>, the session will be immediately +removed again. + +The remove_session_cb() is called, whenever the SSL engine removes a session +from the internal cache. This happens when the session is removed because +it is expired or when a connection was not shutdown cleanly. It also happens +for all sessions in the internal session cache when +L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed +the B<ctx> and the ssl session B<sess>. It does not provide any feedback. + +The get_session_cb() is only called on SSL/TLS servers with the session id +proposed by the client. The get_session_cb() is always called, also when +session caching was disabled. The get_session_cb() is passed the +B<ssl> connection, the session id of length B<length> at the memory location +B<data>. With the parameter B<copy> the callback can require the +SSL engine to increment the reference count of the SSL_SESSION object, +Normally the reference count is not incremented and therefore the +session must not be explicitly freed with +L<SSL_SESSION_free(3)>. + +=head1 SEE ALSO + +L<ssl(3)>, L<d2i_SSL_SESSION(3)>, +L<SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_flush_sessions(3)>, +L<SSL_SESSION_free(3)>, +L<SSL_CTX_free(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod new file mode 100644 index 0000000..bc4a55e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + +SSL_CTX_sessions - access internal session cache + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_sessions() returns a pointer to the lhash databases containing the +internal session cache for B<ctx>. + +=head1 NOTES + +The sessions in the internal session cache are kept in an +L<lhash(3)> type database. It is possible to directly +access this database e.g. for searching. In parallel, the sessions +form a linked list which is maintained separately from the +L<lhash(3)> operations, so that the database must not be +modified directly but by using the +L<SSL_CTX_add_session(3)> family of functions. + +=head1 SEE ALSO + +L<ssl(3)>, L<lhash(3)>, +L<SSL_CTX_add_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod new file mode 100644 index 0000000..b0276c8 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves, +SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve - EC supported curve functions + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); + int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); + + int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); + int SSL_set1_curves_list(SSL *ssl, char *list); + + int SSL_get1_curves(SSL *ssl, int *curves); + int SSL_get_shared_curve(SSL *s, int n); + +=head1 DESCRIPTION + +SSL_CTX_set1_curves() sets the supported curves for B<ctx> to B<clistlen> +curves in the array B<clist>. The array consist of all NIDs of curves in +preference order. For a TLS client the curves are used directly in the +supported curves extension. For a TLS server the curves are used to +determine the set of shared curves. + +SSL_CTX_set1_curves_list() sets the supported curves for B<ctx> to +string B<list>. The string is a colon separated list of curve NIDs or +names, for example "P-521:P-384:P-256". + +SSL_set1_curves() and SSL_set1_curves_list() are similar except they set +supported curves for the SSL structure B<ssl>. + +SSL_get1_curves() returns the set of supported curves sent by a client +in the supported curves extension. It returns the total number of +supported curves. The B<curves> parameter can be B<NULL> to simply +return the number of curves for memory allocation purposes. The +B<curves> array is in the form of a set of curve NIDs in preference +order. It can return zero if the client did not send a supported curves +extension. + +SSL_get_shared_curve() returns shared curve B<n> for a server-side +SSL B<ssl>. If B<n> is -1 then the total number of shared curves is +returned, which may be zero. Other than for diagnostic purposes, +most applications will only be interested in the first shared curve +so B<n> is normally set to zero. If the value B<n> is out of range, +NID_undef is returned. + +All these functions are implemented as macros. + +=head1 NOTES + +If an application wishes to make use of several of these functions for +configuration purposes either on a command line or in a file it should +consider using the SSL_CONF interface instead of manually parsing options. + +=head1 RETURN VALUES + +SSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves() and +SSL_set1_curves_list(), return 1 for success and 0 for failure. + +SSL_get1_curves() returns the number of curves, which may be zero. + +SSL_get_shared_curve() returns the NID of shared curve B<n> or NID_undef if there +is no shared curve B<n>; or the total number of shared curves if B<n> +is -1. + +When called on a client B<ssl>, SSL_get_shared_curve() has no meaning and +returns -1. + +=head1 SEE ALSO + +L<SSL_CTX_add_extra_chain_cert(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod new file mode 100644 index 0000000..e9073b9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod @@ -0,0 +1,113 @@ +=pod + +=head1 NAME + +SSL_CTX_set1_sigalgs, SSL_set1_sigalgs, SSL_CTX_set1_sigalgs_list, +SSL_set1_sigalgs_list, SSL_CTX_set1_client_sigalgs, +SSL_set1_client_sigalgs, SSL_CTX_set1_client_sigalgs_list, +SSL_set1_client_sigalgs_list - set supported signature algorithms + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set1_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); + long SSL_set1_sigalgs(SSL *ssl, const int *slist, long slistlen); + long SSL_CTX_set1_sigalgs_list(SSL_CTX *ctx, const char *str); + long SSL_set1_sigalgs_list(SSL *ssl, const char *str); + + long SSL_CTX_set1_client_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); + long SSL_set1_client_sigalgs(SSL *ssl, const int *slist, long slistlen); + long SSL_CTX_set1_client_sigalgs_list(SSL_CTX *ctx, const char *str); + long SSL_set1_client_sigalgs_list(SSL *ssl, const char *str); + +=head1 DESCRIPTION + +SSL_CTX_set1_sigalgs() and SSL_set1_sigalgs() set the supported signature +algorithms for B<ctx> or B<ssl>. The array B<slist> of length B<slistlen> +must consist of pairs of NIDs corresponding to digest and public key +algorithms. + +SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list() set the supported +signature algorithms for B<ctx> or B<ssl>. The B<str> parameter +must be a null terminated string consisting or a colon separated list of +public key algorithms and digests separated by B<+>. + +SSL_CTX_set1_client_sigalgs(), SSL_set1_client_sigalgs(), +SSL_CTX_set1_client_sigalgs_list() and SSL_set1_client_sigalgs_list() set +signature algorithms related to client authentication, otherwise they are +identical to SSL_CTX_set1_sigalgs(), SSL_set1_sigalgs(), +SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list(). + +All these functions are implemented as macros. The signature algorithm +parameter (integer array or string) is not freed: the application should +free it, if necessary. + +=head1 NOTES + +If an application wishes to allow the setting of signature algorithms +as one of many user configurable options it should consider using the more +flexible SSL_CONF API instead. + +The signature algorithms set by a client are used directly in the supported +signature algorithm in the client hello message. + +The supported signature algorithms set by a server are not sent to the +client but are used to determine the set of shared signature algorithms +and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE) +their order. + +The client authentication signature algorithms set by a server are sent +in a certificate request message if client authentication is enabled, +otherwise they are unused. + +Similarly client authentication signature algorithms set by a client are +used to determined the set of client authentication shared signature +algorithms. + +Signature algorithms will neither be advertised nor used if the security level +prohibits them (for example SHA1 if the security level is 4 or more). + +Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and +NID_sha512 digest NIDs are supported and the public key algorithm NIDs +EVP_PKEY_RSA, EVP_PKEY_DSA and EVP_PKEY_EC. + +The short or long name values for digests can be used in a string (for +example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and +the public key algorithm strings "RSA", "DSA" or "ECDSA". + +The use of MD5 as a digest is strongly discouraged due to security weaknesses. + +=head1 EXAMPLES + +Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA +using an array: + + const int slist[] = {NID_sha256, EVP_PKEY_EC, NID_sha256, EVP_PKEY_RSA}; + + SSL_CTX_set1_sigalgs(ctx, slist, 4); + +Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA +using a string: + + SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256"); + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_get_shared_sigalgs(3)>, +L<SSL_CONF_CTX_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod new file mode 100644 index 0000000..bfe8b70 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +SSL_CTX_set0_verify_cert_store, SSL_CTX_set1_verify_cert_store, +SSL_CTX_set0_chain_cert_store, SSL_CTX_set1_chain_cert_store, +SSL_set0_verify_cert_store, SSL_set1_verify_cert_store, +SSL_set0_chain_cert_store, SSL_set1_chain_cert_store - set certificate +verification or chain store + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); + + int SSL_set0_verify_cert_store(SSL *ctx, X509_STORE *st); + int SSL_set1_verify_cert_store(SSL *ctx, X509_STORE *st); + int SSL_set0_chain_cert_store(SSL *ctx, X509_STORE *st); + int SSL_set1_chain_cert_store(SSL *ctx, X509_STORE *st); + +=head1 DESCRIPTION + +SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store() +set the certificate store used for certificate verification to B<st>. + +SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store() +set the certificate store used for certificate chain building to B<st>. + +SSL_set0_verify_cert_store(), SSL_set1_verify_cert_store(), +SSL_set0_chain_cert_store() and SSL_set1_chain_cert_store() are similar +except they apply to SSL structure B<ssl>. + +All these functions are implemented as macros. Those containing a B<1> +increment the reference count of the supplied store so it must +be freed at some point after the operation. Those containing a B<0> do +not increment reference counts and the supplied store B<MUST NOT> be freed +after the operation. + +=head1 NOTES + +The stores pointers associated with an SSL_CTX structure are copied to any SSL +structures when SSL_new() is called. As a result SSL structures will not be +affected if the parent SSL_CTX store pointer is set to a new value. + +The verification store is used to verify the certificate chain sent by the +peer: that is an SSL/TLS client will use the verification store to verify +the server's certificate chain and a SSL/TLS server will use it to verify +any client certificate chain. + +The chain store is used to build the certificate chain. + +If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set or a certificate chain is +configured already (for example using the functions such as +L<SSL_CTX_add1_chain_cert(3)> or +L<SSL_CTX_add_extra_chain_cert(3)>) then +automatic chain building is disabled. + +If the mode B<SSL_MODE_NO_AUTO_CHAIN> is set then automatic chain building +is disabled. + +If the chain or the verification store is not set then the store associated +with the parent SSL_CTX is used instead to retain compatibility with previous +versions of OpenSSL. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<SSL_CTX_add_extra_chain_cert(3)> +L<SSL_CTX_set0_chain(3)> +L<SSL_CTX_set1_chain(3)> +L<SSL_CTX_add0_chain_cert(3)> +L<SSL_CTX_add1_chain_cert(3)> +L<SSL_set0_chain(3)> +L<SSL_set1_chain(3)> +L<SSL_add0_chain_cert(3)> +L<SSL_add1_chain_cert(3)> +L<SSL_CTX_build_cert_chain(3)> +L<SSL_build_cert_chain(3)> + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod new file mode 100644 index 0000000..56c8609 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod @@ -0,0 +1,197 @@ +=pod + +=head1 NAME + +SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, +SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb, +SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated +- handle application layer protocol negotiation (ALPN) + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos, + unsigned int protos_len); + int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos, + unsigned int protos_len); + void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx, + int (*cb) (SSL *ssl, + const unsigned char **out, + unsigned char *outlen, + const unsigned char *in, + unsigned int inlen, + void *arg), void *arg); + void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, + unsigned int *len); + + void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx, + int (*cb)(SSL *ssl, + const unsigned char **out, + unsigned int *outlen, + void *arg), + void *arg); + void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx, + int (*cb)(SSL *s, + unsigned char **out, + unsigned char *outlen, + const unsigned char *in, + unsigned int inlen, + void *arg), + void *arg); + int SSL_select_next_proto(unsigned char **out, unsigned char *outlen, + const unsigned char *server, + unsigned int server_len, + const unsigned char *client, + unsigned int client_len) + void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data, + unsigned *len); + +=head1 DESCRIPTION + +SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to +set the list of protocols available to be negotiated. The B<protos> must be in +protocol-list format, described below. The length of B<protos> is specified in +B<protos_len>. + +SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a +server to select which protocol to use for the incoming connection. When B<cb> +is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to +the application callback. + +B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a +vector in protocol-list format. The value of the B<out>, B<outlen> vector +should be set to the value of a single protocol selected from the B<in>, +B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a +buffer that outlives the handshake. The B<arg> parameter is the pointer set via +SSL_CTX_set_alpn_select_cb(). + +SSL_select_next_proto() is a helper function used to select protocols. It +implements the standard protocol selection. It is expected that this function +is called from the application callback B<cb>. The protocol data in B<server>, +B<server_len> and B<client>, B<client_len> must be in the protocol-list format +described below. The first item in the B<server>, B<server_len> list that +matches an item in the B<client>, B<client_len> list is selected, and returned +in B<out>, B<outlen>. The B<out> value will point into either B<server> or +B<client>, so it should be copied immediately. If no match is found, the first +item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This +function can also be used in the NPN callback. + +SSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a +client needs to select a protocol from the server's provided list, and a +user-defined pointer argument B<arg> which will be passed to this callback. +For the callback itself, B<out> +must be set to point to the selected protocol (which may be within B<in>). +The length of the protocol name must be written into B<outlen>. The +server's advertised protocols are provided in B<in> and B<inlen>. The +callback can assume that B<in> is syntactically valid. The client must +select a protocol. It is fatal to the connection if this callback returns +a value other than B<SSL_TLSEXT_ERR_OK>. The B<arg> parameter is the pointer +set via SSL_CTX_set_next_proto_select_cb(). + +SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called +when a TLS server needs a list of supported protocols for Next Protocol +Negotiation. The returned list must be in protocol-list format, described +below. The list is +returned by setting B<out> to point to it and B<outlen> to its length. This +memory will not be modified, but the B<SSL> does keep a +reference to it. The callback should return B<SSL_TLSEXT_ERR_OK> if it +wishes to advertise. Otherwise, no such extension will be included in the +ServerHello. + +SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data> +with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len> +is set to 0 if no protocol has been selected. B<data> must not be freed. + +SSL_get0_next_proto_negotiated() sets B<data> and B<len> to point to the +client's requested protocol for this connection. If the client did not +request any protocol or NPN is not enabled, then B<data> is set to NULL and +B<len> to 0. Note that +the client can request any protocol it chooses. The value returned from +this function need not be a member of the list of supported protocols +provided by the callback. + +=head1 NOTES + +The protocol-lists must be in wire-format, which is defined as a vector of +non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not +included in the length. Each string is limited to 255 bytes. A byte-string +length of 0 is invalid. A truncated byte-string is invalid. The length of the +vector is not in the vector itself, but in a separate variable. + +Example: + + unsigned char vector[] = { + 6, 's', 'p', 'd', 'y', '/', '1', + 8, 'h', 't', 't', 'p', '/', '1', '.', '1' + }; + unsigned int length = sizeof(vector); + +The ALPN callback is executed after the servername callback; as that servername +callback may update the SSL_CTX, and subsequently, the ALPN callback. + +If there is no ALPN proposed in the ClientHello, the ALPN callback is not +invoked. + +=head1 RETURN VALUES + +SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and +non-0 on failure. WARNING: these functions reverse the return value convention. + +SSL_select_next_proto() returns one of the following: + +=over 4 + +=item OPENSSL_NPN_NEGOTIATED + +A match was found and is returned in B<out>, B<outlen>. + +=item OPENSSL_NPN_NO_OVERLAP + +No match was found. The first item in B<client>, B<client_len> is returned in +B<out>, B<outlen>. + +=back + +The ALPN select callback B<cb>, must return one of the following: + +=over 4 + +=item SSL_TLSEXT_ERR_OK + +ALPN protocol selected. + +=item SSL_TLSEXT_ERR_ALERT_FATAL + +There was no overlap between the client's supplied list and the server +configuration. + +=item SSL_TLSEXT_ERR_NOACK + +ALPN protocol not selected, e.g., because no ALPN protocols are configured for +this connection. + +=back + +The callback set using SSL_CTX_set_next_proto_select_cb() should return +B<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection. + +The callback set using SSL_CTX_set_next_protos_advertised_cb() should return +B<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension +will be included in the ServerHello. + +=head1 SEE ALSO + +L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, +L<SSL_CTX_set_tlsext_servername_arg(3)> + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod new file mode 100644 index 0000000..eaa7a4e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); + void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); + + int (*cert_cb)(SSL *ssl, void *arg); + +=head1 DESCRIPTION + +SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb() callback, +B<arg> value is pointer which is passed to the application callback. + +When cert_cb() is NULL, no callback function is used. + +cert_cb() is the application defined callback. It is called before a +certificate will be used by a client or server. The callback can then inspect +the passed B<ssl> structure and set or clear any appropriate certificates. If +the callback is successful it B<MUST> return 1 even if no certificates have +been set. A zero is returned on error which will abort the handshake with a +fatal internal error alert. A negative return value will suspend the handshake +and the handshake function will return immediately. +L<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 cert_cb(). It is the job of the +cert_cb() to store information about the state of the last call, +if required to continue. + +=head1 NOTES + +An application will typically call SSL_use_certificate() and +SSL_use_PrivateKey() to set the end entity certificate and private key. +It can add intermediate and optionally the root CA certificates using +SSL_add1_chain_cert(). + +It might also call SSL_certs_clear() to delete any certificates associated +with the B<SSL> object. + +The certificate callback functionality supersedes the (largely broken) +functionality provided by the old client certificate callback interface. +It is B<always> called even is a certificate is already set so the callback +can modify or delete the existing certificate. + +A more advanced callback might examine the handshake parameters and set +whatever chain is appropriate. For example a legacy client supporting only +TLS v1.0 might receive a certificate chain signed using SHA1 whereas a +TLS v1.2 client which advertises support for SHA256 could receive a chain +using SHA256. + +Normal server sanity checks are performed on any certificates set +by the callback. So if an EC chain is set for a curve the client does not +support it will B<not> be used. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_use_certificate(3)>, +L<SSL_add1_chain_cert(3)>, +L<SSL_get_client_CA_list(3)>, +L<SSL_clear(3)>, L<SSL_free(3)> + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod new file mode 100644 index 0000000..7f7a794 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate verification storage + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store); + X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_cert_store() sets/replaces the certificate verification storage +of B<ctx> to/with B<store>. If another X509_STORE object is currently +set in B<ctx>, it will be X509_STORE_free()ed. + +SSL_CTX_get_cert_store() returns a pointer to the current certificate +verification storage. + +=head1 NOTES + +In order to verify the certificates presented by the peer, trusted CA +certificates must be accessed. These CA certificates are made available +via lookup methods, handled inside the X509_STORE. From the X509_STORE +the X509_STORE_CTX used when verifying certificates is created. + +Typically the trusted certificate store is handled indirectly via using +L<SSL_CTX_load_verify_locations(3)>. +Using the SSL_CTX_set_cert_store() and SSL_CTX_get_cert_store() functions +it is possible to manipulate the X509_STORE object beyond the +L<SSL_CTX_load_verify_locations(3)> +call. + +Currently no detailed documentation on how to use the X509_STORE +object is available. Not all members of the X509_STORE are used when +the verification takes place. So will e.g. the verify_callback() be +overridden with the verify_callback() set via the +L<SSL_CTX_set_verify(3)> family of functions. +This document must therefore be updated when documentation about the +X509_STORE object and its handling becomes available. + +=head1 RESTRICTIONS + +The X509_STORE structure used by an SSL_CTX is used for verifying peer +certificates and building certificate chains, it is also shared by +every child SSL structure. Applications wanting finer control can use +functions such as SSL_CTX_set1_verify_cert_store() instead. + +=head1 RETURN VALUES + +SSL_CTX_set_cert_store() does not return diagnostic output. + +SSL_CTX_get_cert_store() returns the current setting. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_load_verify_locations(3)>, +L<SSL_CTX_set_verify(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod new file mode 100644 index 0000000..af303f2 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *, void *), void *arg); + +=head1 DESCRIPTION + +SSL_CTX_set_cert_verify_callback() sets the verification callback function for +I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at +the time when L<SSL_new(3)> is called. + +=head1 NOTES + +Whenever a certificate is verified during a SSL/TLS handshake, a verification +function is called. If the application does not explicitly specify a +verification callback function, the built-in verification function is used. +If a verification callback I<callback> is specified via +SSL_CTX_set_cert_verify_callback(), the supplied callback function is called +instead. By setting I<callback> to NULL, the default behaviour is restored. + +When the verification must be performed, I<callback> will be called with +the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The +argument I<arg> is specified by the application when setting I<callback>. + +I<callback> should return 1 to indicate verification success and 0 to +indicate verification failure. If SSL_VERIFY_PEER is set and I<callback> +returns 0, the handshake will fail. As the verification procedure may +allow to continue the connection in case of failure (by always returning 1) +the verification result must be set in any case using the B<error> +member of I<x509_store_ctx> so that the calling application will be informed +about the detailed result of the verification procedure! + +Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback> +function set using L<SSL_CTX_set_verify(3)>. + +=head1 WARNINGS + +Do not mix the verification callback described in this function with the +B<verify_callback> function called during the verification process. The +latter is set using the L<SSL_CTX_set_verify(3)> +family of functions. + +Providing a complete verification procedure including certificate purpose +settings etc is a complex task. The built-in procedure is quite powerful +and in most cases it should be sufficient to modify its behaviour using +the B<verify_callback> function. + +=head1 BUGS + +SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_CTX_set_verify(3)>, +L<SSL_get_verify_result(3)>, +L<SSL_CTX_load_verify_locations(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod new file mode 100644 index 0000000..4e66917 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); + int SSL_set_cipher_list(SSL *ssl, const char *str); + +=head1 DESCRIPTION + +SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx> +using the control string B<str>. The format of the string is described +in L<ciphers(1)>. The list of ciphers is inherited by all +B<ssl> objects created from B<ctx>. + +SSL_set_cipher_list() sets the list of ciphers only for B<ssl>. + +=head1 NOTES + +The control string B<str> should be universally usable and not depend +on details of the library configuration (ciphers compiled in). Thus no +syntax checking takes place. Items that are not recognized, because the +corresponding ciphers are not compiled in or because they are mistyped, +are simply ignored. Failure is only flagged if no ciphers could be collected +at all. + +It should be noted, that inclusion of a cipher to be used into the list is +a necessary condition. On the client side, the inclusion into the list is +also sufficient unless the security level excludes it. On the server side, +additional restrictions apply. All ciphers have additional requirements. +ADH ciphers don't need a certificate, but DH-parameters must have been set. +All other ciphers need a corresponding certificate and key. + +A RSA cipher can only be chosen, when a RSA certificate is available. +RSA ciphers using DHE need a certificate and key and additional DH-parameters +(see L<SSL_CTX_set_tmp_dh_callback(3)>). + +A DSA cipher can only be chosen, when a DSA certificate is available. +DSA ciphers always use DH key exchange and therefore need DH-parameters +(see L<SSL_CTX_set_tmp_dh_callback(3)>). + +When these conditions are not met for any cipher in the list (e.g. a +client only supports export RSA ciphers with an asymmetric key length +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. + +=head1 RETURN VALUES + +SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher +could be selected and 0 on complete failure. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_get_ciphers(3)>, +L<SSL_CTX_use_certificate(3)>, +L<SSL_CTX_set_tmp_dh_callback(3)>, +L<ciphers(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod new file mode 100644 index 0000000..0252e7b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod @@ -0,0 +1,103 @@ +=pod + +=head1 NAME + +SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, +SSL_add_client_CA - set list of CAs sent to the client when requesting a +client certificate + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); + void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); + int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); + int SSL_add_client_CA(SSL *ssl, X509 *cacert); + +=head1 DESCRIPTION + +SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when +requesting a client certificate for B<ctx>. + +SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when +requesting a client certificate for the chosen B<ssl>, overriding the +setting valid for B<ssl>'s SSL_CTX object. + +SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the +list of CAs sent to the client when requesting a client certificate for +B<ctx>. + +SSL_add_client_CA() adds the CA name extracted from B<cacert> to the +list of CAs sent to the client when requesting a client certificate for +the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object. + +=head1 NOTES + +When a TLS/SSL server requests a client certificate (see +B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which +it will accept certificates, to the client. + +This list must explicitly be set using SSL_CTX_set_client_CA_list() for +B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list +specified overrides the previous setting. The CAs listed do not become +trusted (B<list> only contains the names, not the complete certificates); use +L<SSL_CTX_load_verify_locations(3)> +to additionally load them for verification. + +If the list of acceptable CAs is compiled in a file, the +L<SSL_load_client_CA_file(3)> +function can be used to help importing the necessary data. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional +items the list of client CAs. If no list was specified before using +SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client +CA list for B<ctx> or B<ssl> (as appropriate) is opened. + +These functions are only useful for TLS/SSL servers. + +=head1 RETURN VALUES + +SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return +diagnostic information. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return +values: + +=over 4 + +=item Z<>0 + +A failure while manipulating the STACK_OF(X509_NAME) object occurred or +the X509_NAME could not be extracted from B<cacert>. Check the error stack +to find out the reason. + +=item Z<>1 + +The operation succeeded. + +=back + +=head1 EXAMPLES + +Scan all certificates in B<CAfile> and list them as acceptable CAs: + + SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile)); + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_get_client_CA_list(3)>, +L<SSL_load_client_CA_file(3)>, +L<SSL_CTX_load_verify_locations(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod new file mode 100644 index 0000000..aed7d4f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod @@ -0,0 +1,103 @@ +=pod + +=head1 NAME + +SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certificate callback function + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); + int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); + int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey); + +=head1 DESCRIPTION + +SSL_CTX_set_client_cert_cb() sets the client_cert_cb() callback, that is +called when a client certificate is requested by a server and no certificate +was yet set for the SSL object. + +When client_cert_cb() is NULL, no callback function is used. + +SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback +function. + +client_cert_cb() is the application defined callback. If it wants to +set a certificate, a certificate/private key combination must be set +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 immediately. L<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 +about the state of the last call, if required to continue. + +=head1 NOTES + +During a handshake (or renegotiation) a server may request a certificate +from the client. A client certificate must only be sent, when the server +did send the request. + +When a certificate was set using the +L<SSL_CTX_use_certificate(3)> family of functions, +it will be sent to the server. The TLS standard requires that only a +certificate is sent, if it matches the list of acceptable CAs sent by the +server. This constraint is violated by the default behavior of the OpenSSL +library. Using the callback function it is possible to implement a proper +selection routine or to allow a user interaction to choose the certificate to +be sent. + +If a callback function is defined and no certificate was yet defined for the +SSL object, the callback function will be called. +If the callback function returns a certificate, the OpenSSL library +will try to load the private key and certificate data into the SSL +object using the SSL_use_certificate() and SSL_use_private_key() functions. +Thus it will permanently install the certificate and key for this SSL +object. It will not be reset by calling L<SSL_clear(3)>. +If the callback returns no certificate, the OpenSSL library will not send +a certificate. + +=head1 BUGS + +The client_cert_cb() cannot return a complete certificate chain, it can +only return one client certificate. If the chain only has a length of 2, +the root CA certificate may be omitted according to the TLS standard and +thus a standard conforming answer can be sent to the server. For a +longer chain, the client must send the complete chain (with the option +to leave out the root CA certificate). This can only be accomplished by +either adding the intermediate CA certificates into the trusted +certificate store for the SSL_CTX object (resulting in having to add +CA certificates that otherwise maybe would not be trusted), or by adding +the chain certificates using the +L<SSL_CTX_add_extra_chain_cert(3)> +function, which is only available for the SSL_CTX object as a whole and that +therefore probably can only apply for one client certificate, making +the concept of the callback function (to allow the choice from several +certificates) questionable. + +Once the SSL object has been used in conjunction with the callback function, +the certificate will be set for the SSL object and will not be cleared +even when L<SSL_clear(3)> is being called. It is therefore +mandatory to destroy the SSL object using L<SSL_free(3)> +and create a new one to return to the previous state. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_CTX_use_certificate(3)>, +L<SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_get_client_CA_list(3)>, +L<SSL_clear(3)>, L<SSL_free(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod new file mode 100644 index 0000000..afa45dc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod @@ -0,0 +1,145 @@ +=pod + +=head1 NAME + +ssl_ct_validation_cb, +SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, +SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, +SSL_ct_is_enabled, SSL_CTX_ct_is_enabled - +control Certificate Transparency policy + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx, + const STACK_OF(SCT) *scts, void *arg); + + int SSL_enable_ct(SSL *s, int validation_mode); + int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode); + int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, + void *arg); + int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, + ssl_ct_validation_cb callback, + void *arg); + void SSL_disable_ct(SSL *s); + void SSL_CTX_disable_ct(SSL_CTX *ctx); + int SSL_ct_is_enabled(const SSL *s); + int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed +certificate timestamps (SCTs) either for a given SSL connection or for all +connections that share the given SSL context, respectively. +This is accomplished by setting a built-in CT validation callback. +The behaviour of the callback is determined by the B<validation_mode> argument, +which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or +B<SSL_CT_VALIDATION_STRICT> as described below. + +If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full +TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer +presents no valid SCTs the handshake will be aborted. +If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue +despite lack of valid SCTs. +However, in that case if the verification status before the built-in callback +was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the +callback. +Applications can call L<SSL_get_verify_result(3)> to check the status at +handshake completion, even after session resumption since the verification +status is part of the saved session state. +See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>. + +If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the +handshake continues, and the verification status is not modified, regardless of +the validation status of any SCTs. +The application can still inspect the validation status of the SCTs at +handshake completion. +Note that with session resumption there will not be any SCTs presented during +the handshake. +Therefore, in applications that delay SCT policy enforcement until after +handshake completion, such delayed SCT checks should only be performed when the +session is not resumed. + +SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() +register a custom callback that may implement a different policy than either of +the above. +This callback can examine the peer's SCTs and determine whether they are +sufficient to allow the connection to continue. +The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE> +and the callback returns a non-positive result. + +An arbitrary callback context argument, B<arg>, can be passed in when setting +the callback. +This will be passed to the callback whenever it is invoked. +Ownership of this context remains with the caller. + +If no callback is set, SCTs will not be requested and Certificate Transparency +validation will not occur. + +No callback will be invoked when the peer presents no certificate, e.g. by +employing an anonymous (aNULL) ciphersuite. +In that case the handshake continues as it would had no callback been +requested. +Callbacks are also not invoked when the peer certificate chain is invalid or +validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509 +PKI, or no X.509 PKI at all, respectively. +Clients that require SCTs are expected to not have enabled any aNULL ciphers +nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA +records. + +SSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether +enabled via the built-in or the custom callbacks, by setting a NULL callback. +These may be implemented as macros. + +SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is +enabled via either SSL_enable_ct() or a non-null custom callback, and 0 +otherwise. + +=head1 NOTES + +When SCT processing is enabled, OCSP stapling will be enabled. This is because +one possible source of SCTs is the OCSP response from a server. + +The time returned by SSL_SESSION_get_time() will be used to evaluate whether any +presented SCTs have timestamps that are in the future (and therefore invalid). + +=head1 RESTRICTIONS + +Certificate Transparency validation cannot be enabled and so a callback cannot +be set if a custom client extension handler has been registered to handle SCT +extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>). + +=head1 RETURN VALUES + +SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and +SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully +set. +They return 0 if an error occurs, e.g. a custom client extension handler has +been setup to handle SCTs. + +SSL_disable_ct() and SSL_CTX_disable_ct() do not return a result. + +SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT +validation callback is set, or 0 if no callback (or equivalently a NULL +callback) is set. + +=head1 SEE ALSO + +L<ssl(7)>, +<SSL_get_verify_result(3)>, +L<SSL_session_reused(3)>, +L<SSL_set_verify(3)>, +L<SSL_CTX_set_verify(3)>, +L<SSL_SESSION_get_time(3)> + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod new file mode 100644 index 0000000..4a2fa94 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file - +load a Certificate Transparency log list from a file + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx); + int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path); + +=head1 DESCRIPTION + +SSL_CTX_set_default_ctlog_list_file() loads a list of Certificate Transparency +(CT) logs from the default file location, "ct_log_list.cnf", found in the +directory where OpenSSL is installed. + +SSL_CTX_set_ctlog_list_file() loads a list of CT logs from a specific path. +See L<CTLOG_STORE_new(3)> for the file format. + +=head1 NOTES + +These functions will not clear the existing CT log list - it will be appended +to. To replace the existing list, use L<SSL_CTX_set0_ctlog_store> first. + +If an error occurs whilst parsing a particular log entry in the file, that log +entry will be skipped. + +=head1 RETURN VALUES + +SSL_CTX_set_default_ctlog_list_file() and SSL_CTX_set_ctlog_list_file() +return 1 if the log list is successfully loaded, and 0 if an error occurs. In +the case of an error, the log list may have been partially loaded. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_ct_validation_callback(3)>, +L<CTLOG_STORE_new(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod new file mode 100644 index 0000000..2196906 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod @@ -0,0 +1,113 @@ +=pod + +=head1 NAME + +SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata, +SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata, +SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata, +SSL_get_default_passwd_cb, SSL_get_default_passwd_cb_userdata - set or +get passwd callback for encrypted PEM file handling + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); + void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); + pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx); + void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx); + + void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb); + void SSL_set_default_passwd_cb_userdata(SSL *s, void *u); + pem_password_cb *SSL_get_default_passwd_cb(SSL *s); + void *SSL_get_default_passwd_cb_userdata(SSL *s); + +=head1 DESCRIPTION + +SSL_CTX_set_default_passwd_cb() sets the default password callback called +when loading/storing a PEM certificate with encryption. + +SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to userdata, B<u>, +which will be provided to the password callback on invocation. + +SSL_CTX_get_default_passwd_cb() returns a function pointer to the password +callback currently set in B<ctx>. If no callback was explicitly set, the +NULL pointer is returned. + +SSL_CTX_get_default_passwd_cb_userdata() returns a pointer to the userdata +currently set in B<ctx>. If no userdata was explicitly set, the NULL pointer +is returned. + +SSL_set_default_passwd_cb(), SSL_set_default_passwd_cb_userdata(), +SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() perform +the same function as their SSL_CTX counterparts, but using an SSL object. + +The password callback, which must be provided by the application, hands back the +password to be used during decryption. +On invocation a pointer to userdata +is provided. The function must store the password into the provided buffer +B<buf> which is of size B<size>. The actual length of the password must +be returned to the calling function. B<rwflag> indicates whether the +callback is used for reading/decryption (rwflag=0) or writing/encryption +(rwflag=1). +For more details, see L<pem_password_cb(3)>. + +=head1 NOTES + +When loading or storing private keys, a password might be supplied to +protect the private key. The way this password can be supplied may depend +on the application. If only one private key is handled, it can be practical +to have the callback handle the password dialog interactively. If several +keys have to be handled, it can be practical to ask for the password once, +then keep it in memory and use it several times. In the last case, the +password could be stored into the userdata storage and the +callback only returns the password already stored. + +When asking for the password interactively, the callback can use +B<rwflag> to check, whether an item shall be encrypted (rwflag=1). +In this case the password dialog may ask for the same password twice +for comparison in order to catch typos, that would make decryption +impossible. + +Other items in PEM formatting (certificates) can also be encrypted, it is +however not usual, as certificate information is considered public. + +=head1 RETURN VALUES + +These functions do not provide diagnostic information. + +=head1 EXAMPLES + +The following example returns the password provided as userdata to the +calling function. The password is considered to be a '\0' terminated +string. If the password does not fit into the buffer, the password is +truncated. + + int my_cb(char *buf, int size, int rwflag, void *u) + { + strncpy(buf, (char *)u, size); + buf[size - 1] = '\0'; + return strlen(buf); + } + +=head1 HISTORY + +SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(), +SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were +first added to OpenSSL 1.1.0 + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_use_certificate(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod new file mode 100644 index 0000000..fd0364b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SSL_CTX_get_ex_data, SSL_CTX_set_ex_data, +SSL_get_ex_data, SSL_set_ex_data +- Store and retrieve extra data from the SSL_CTX, SSL or SSL_SESSION + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx); + + int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, void *arg); + + void *SSL_get_ex_data(const SSL *s, int idx); + + int SSL_set_ex_data(SSL *s, int idx, void *arg); + +=head1 DESCRIPTION + +SSL*_set_ex_data() functions can be used to store arbitrary user data into the +B<SSL_CTX>, or B<SSL> object. The user must supply a unique index +which they can subsequently use to retrieve the data using SSL*_get_ex_data(). + +For more detailed information see L<CRYPTO_get_ex_data(3)> and +L<CRYPTO_set_ex_data(3)> which implement these functions and +L<CRYPTO_get_ex_new_index(3)> for generating a unique index. + +=head1 RETURN VALUES + +The SSL*_set_ex_data() functions return 1 if the item is successfully stored +and 0 if it is not. +The SSL*_get_ex_data() functions return the ex_data pointer if successful, +otherwise NULL. + +=head1 SEE ALSO + +L<CRYPTO_get_ex_data(3)>, L<CRYPTO_set_ex_data(3)>, +L<CRYPTO_get_ex_new_index(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod new file mode 100644 index 0000000..1b1171f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod @@ -0,0 +1,139 @@ +=pod + +=head1 NAME + +SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, +SSL_has_matching_session_id, GEN_SESSION_CB +- manipulate generation of SSL session IDs (server only) + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id, + unsigned int *id_len); + + int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb); + int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb); + int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id, + unsigned int id_len); + +=head1 DESCRIPTION + +SSL_CTX_set_generate_session_id() sets the callback function for generating +new session ids for SSL/TLS sessions for B<ctx> to be B<cb>. + +SSL_set_generate_session_id() sets the callback function for generating +new session ids for SSL/TLS sessions for B<ssl> to be B<cb>. + +SSL_has_matching_session_id() checks, whether a session with id B<id> +(of length B<id_len>) is already contained in the internal session cache +of the parent context of B<ssl>. + +=head1 NOTES + +When a new session is established between client and server, the server +generates a session id. The session id is an arbitrary sequence of bytes. +The length of the session id is between 1 and 32 bytes. The session id is not +security critical but must be unique for the server. Additionally, the session id is +transmitted in the clear when reusing the session so it must not contain +sensitive information. + +Without a callback being set, an OpenSSL server will generate a unique +session id from pseudo random numbers of the maximum possible length. +Using the callback function, the session id can be changed to contain +additional information like e.g. a host id in order to improve load balancing +or external caching techniques. + +The callback function receives a pointer to the memory location to put +B<id> into and a pointer to the maximum allowed length B<id_len>. The +buffer at location B<id> is only guaranteed to have the size B<id_len>. +The callback is only allowed to generate a shorter id and reduce B<id_len>; +the callback B<must never> increase B<id_len> or write to the location +B<id> exceeding the given limit. + +The location B<id> is filled with 0x00 before the callback is called, so the +callback may only fill part of the possible length and leave B<id_len> +untouched while maintaining reproducibility. + +Since the sessions must be distinguished, session ids must be unique. +Without the callback a random number is used, so that the probability +of generating the same session id is extremely small (2^256 for SSLv3/TLSv1). +In order to assure the uniqueness of the generated session id, the callback must call +SSL_has_matching_session_id() and generate another id if a conflict occurs. +If an id conflict is not resolved, the handshake will fail. +If the application codes e.g. a unique host id, a unique process number, and +a unique sequence number into the session id, uniqueness could easily be +achieved without randomness added (it should however be taken care that +no confidential information is leaked this way). If the application can not +guarantee uniqueness, it is recommended to use the maximum B<id_len> and +fill in the bytes not used to code special information with random data +to avoid collisions. + +SSL_has_matching_session_id() will only query the internal session cache, +not the external one. Since the session id is generated before the +handshake is completed, it is not immediately added to the cache. If +another thread is using the same internal session cache, a race condition +can occur in that another thread generates the same session id. +Collisions can also occur when using an external session cache, since +the external cache is not tested with SSL_has_matching_session_id() +and the same race condition applies. + +The callback must return 0 if it cannot generate a session id for whatever +reason and return 1 on success. + +=head1 EXAMPLES + +The callback function listed will generate a session id with the +server id given, and will fill the rest with pseudo random bytes: + + const char session_id_prefix = "www-18"; + + #define MAX_SESSION_ID_ATTEMPTS 10 + static int generate_session_id(const SSL *ssl, unsigned char *id, + unsigned int *id_len) + { + unsigned int count = 0; + do { + RAND_pseudo_bytes(id, *id_len); + /* + * Prefix the session_id with the required prefix. NB: If our + * prefix is too long, clip it - but there will be worse effects + * anyway, eg. the server could only possibly create 1 session + * ID (ie. the prefix!) so all future session negotiations will + * fail due to conflicts. + */ + memcpy(id, session_id_prefix, + (strlen(session_id_prefix) < *id_len) ? + strlen(session_id_prefix) : *id_len); + } + while (SSL_has_matching_session_id(ssl, id, *id_len) && + (++count < MAX_SESSION_ID_ATTEMPTS)); + if (count >= MAX_SESSION_ID_ATTEMPTS) + return 0; + return 1; + } + + +=head1 RETURN VALUES + +SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id() +always return 1. + +SSL_has_matching_session_id() returns 1 if another session with the +same id is already in the cache. + +=head1 SEE ALSO + +L<ssl(7)>, L<SSL_get_version(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod new file mode 100644 index 0000000..f36f217 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod @@ -0,0 +1,162 @@ +=pod + +=head1 NAME + +SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, SSL_get_info_callback - handle information callback for SSL connections + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)()); + void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(); + + void SSL_set_info_callback(SSL *ssl, void (*callback)()); + void (*SSL_get_info_callback(const SSL *ssl))(); + +=head1 DESCRIPTION + +SSL_CTX_set_info_callback() sets the B<callback> function, that can be used to +obtain state information for SSL objects created from B<ctx> during connection +setup and use. The setting for B<ctx> is overridden from the setting for +a specific SSL object, if specified. +When B<callback> is NULL, no callback function is used. + +SSL_set_info_callback() sets the B<callback> function, that can be used to +obtain state information for B<ssl> during connection setup and use. +When B<callback> is NULL, the callback setting currently valid for +B<ctx> is used. + +SSL_CTX_get_info_callback() returns a pointer to the currently set information +callback function for B<ctx>. + +SSL_get_info_callback() returns a pointer to the currently set information +callback function for B<ssl>. + +=head1 NOTES + +When setting up a connection and during use, it is possible to obtain state +information from the SSL/TLS engine. When set, an information callback function +is called whenever the state changes, an alert appears, or an error occurs. + +The callback function is called as B<callback(SSL *ssl, int where, int ret)>. +The B<where> argument specifies information about where (in which context) +the callback function was called. If B<ret> is 0, an error condition occurred. +If an alert is handled, SSL_CB_ALERT is set and B<ret> specifies the alert +information. + +B<where> is a bitmask made up of the following bits: + +=over 4 + +=item SSL_CB_LOOP + +Callback has been called to indicate state change inside a loop. + +=item SSL_CB_EXIT + +Callback has been called to indicate error exit of a handshake function. +(May be soft error with retry option for non-blocking setups.) + +=item SSL_CB_READ + +Callback has been called during read operation. + +=item SSL_CB_WRITE + +Callback has been called during write operation. + +=item SSL_CB_ALERT + +Callback has been called due to an alert being sent or received. + +=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ) + +=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE) + +=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP) + +=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT) + +=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP) + +=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT) + +=item SSL_CB_HANDSHAKE_START + +Callback has been called because a new handshake is started. + +=item SSL_CB_HANDSHAKE_DONE 0x20 + +Callback has been called because a handshake is finished. + +=back + +The current state information can be obtained using the +L<SSL_state_string(3)> family of functions. + +The B<ret> information can be evaluated using the +L<SSL_alert_type_string(3)> family of functions. + +=head1 RETURN VALUES + +SSL_set_info_callback() does not provide diagnostic information. + +SSL_get_info_callback() returns the current setting. + +=head1 EXAMPLES + +The following example callback function prints state strings, information +about alerts being handled and error messages to the B<bio_err> BIO. + + void apps_ssl_info_callback(SSL *s, int where, int ret) + { + const char *str; + int w; + + w = where & ~SSL_ST_MASK; + + if (w & SSL_ST_CONNECT) str = "SSL_connect"; + else if (w & SSL_ST_ACCEPT) str = "SSL_accept"; + else str = "undefined"; + + if (where & SSL_CB_LOOP) + { + BIO_printf(bio_err, "%s:%s\n", str, SSL_state_string_long(s)); + } + else if (where & SSL_CB_ALERT) + { + str = (where & SSL_CB_READ) ? "read" : "write"; + BIO_printf(bio_err, "SSL3 alert %s:%s:%s\n", + str, + SSL_alert_type_string_long(ret), + SSL_alert_desc_string_long(ret)); + } + else if (where & SSL_CB_EXIT) + { + if (ret == 0) + BIO_printf(bio_err, "%s:failed in %s\n", + str, SSL_state_string_long(s)); + else if (ret < 0) + { + BIO_printf(bio_err, "%s:error in %s\n", + str, SSL_state_string_long(s)); + } + } + } + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_state_string(3)>, +L<SSL_alert_type_string(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod new file mode 100644 index 0000000..482751e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list - manipulate allowed size for the peer's certificate chain + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size); + long SSL_CTX_get_max_cert_list(SSL_CTX *ctx); + + long SSL_set_max_cert_list(SSL *ssl, long size); + long SSL_get_max_cert_list(SSL *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_max_cert_list() sets the maximum size allowed for the peer's +certificate chain for all SSL objects created from B<ctx> to be <size> bytes. +The SSL objects inherit the setting valid for B<ctx> at the time +L<SSL_new(3)> is being called. + +SSL_CTX_get_max_cert_list() returns the currently set maximum size for B<ctx>. + +SSL_set_max_cert_list() sets the maximum size allowed for the peer's +certificate chain for B<ssl> to be <size> bytes. This setting stays valid +until a new value is set. + +SSL_get_max_cert_list() returns the currently set maximum size for B<ssl>. + +=head1 NOTES + +During the handshake process, the peer may send a certificate chain. +The TLS/SSL standard does not give any maximum size of the certificate chain. +The OpenSSL library handles incoming data by a dynamically allocated buffer. +In order to prevent this buffer from growing without bounds due to data +received from a faulty or malicious peer, a maximum size for the certificate +chain is set. + +The default value for the maximum certificate chain size is 100kB (30kB +on the 16bit DOS platform). This should be sufficient for usual certificate +chains (OpenSSL's default maximum chain length is 10, see +L<SSL_CTX_set_verify(3)>, and certificates +without special extensions have a typical size of 1-2kB). + +For special applications it can be necessary to extend the maximum certificate +chain size allowed to be sent by the peer, see e.g. the work on +"Internet X.509 Public Key Infrastructure Proxy Certificate Profile" +and "TLS Delegation Protocol" at http://www.ietf.org/ and +http://www.globus.org/ . + +Under normal conditions it should never be necessary to set a value smaller +than the default, as the buffer is handled dynamically and only uses the +memory actually required by the data sent by the peer. + +If the maximum certificate chain size allowed is exceeded, the handshake will +fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error. + +=head1 RETURN VALUES + +SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously +set value. + +SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently +set value. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_new(3)>, +L<SSL_CTX_set_verify(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod new file mode 100644 index 0000000..ff080e4 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, +SSL_CTX_get_min_proto_version, SSL_CTX_get_max_proto_version, +SSL_set_min_proto_version, SSL_set_max_proto_version, +SSL_get_min_proto_version, SSL_get_max_proto_version - Get and set minimum +and maximum supported protocol version + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version); + int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version); + int SSL_CTX_get_min_proto_version(SSL_CTX *ctx); + int SSL_CTX_get_max_proto_version(SSL_CTX *ctx); + + int SSL_set_min_proto_version(SSL *ssl, int version); + int SSL_set_max_proto_version(SSL *ssl, int version); + int SSL_get_min_proto_version(SSL *ssl); + int SSL_get_max_proto_version(SSL *ssl); + +=head1 DESCRIPTION + +The functions get or set the minimum and maximum supported protocol versions +for the B<ctx> or B<ssl>. +This works in combination with the options set via +L<SSL_CTX_set_options(3)> that also make it possible to disable +specific protocol versions. +Use these functions instead of disabling specific protocol versions. + +Setting the minimum or maximum version to 0, will enable protocol +versions down to the lowest version, or up to the highest version +supported by the library, respectively. + +Getters return 0 in case B<ctx> or B<ssl> have been configured to +automatically use the lowest or highest version supported by the library. + +Currently supported versions are B<SSL3_VERSION>, B<TLS1_VERSION>, +B<TLS1_1_VERSION>, B<TLS1_2_VERSION> for TLS and B<DTLS1_VERSION>, +B<DTLS1_2_VERSION> for DTLS. + +=head1 RETURN VALUES + +These setter functions return 1 on success and 0 on failure. The getter +functions return the configured version or 0 for auto-configuration of +lowest or highest protocol, respectively. + +=head1 NOTES + +All these functions are implemented using macros. + +=head1 HISTORY + +The setter functions were added in OpenSSL 1.1.0. The getter functions +were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<SSL_CTX_set_options(3)>, L<SSL_CONF_cmd(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod new file mode 100644 index 0000000..1b3e783 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod @@ -0,0 +1,114 @@ +=pod + +=head1 NAME + +SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); + long SSL_set_mode(SSL *ssl, long mode); + + long SSL_CTX_get_mode(SSL_CTX *ctx); + long SSL_get_mode(SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>. +Options already set before are not cleared. + +SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>. +Options already set before are not cleared. + +SSL_CTX_get_mode() returns the mode set for B<ctx>. + +SSL_get_mode() returns the mode set for B<ssl>. + +=head1 NOTES + +The following mode changes are available: + +=over 4 + +=item SSL_MODE_ENABLE_PARTIAL_WRITE + +Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success +when just a single record has been written). When not set (the default), +SSL_write() will only report success once the complete chunk was written. +Once SSL_write() returns with r, r bytes have been successfully written +and the next call to SSL_write() must only send the n-r bytes left, +imitating the behaviour of write(). + +=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER + +Make it possible to retry SSL_write() with changed buffer location +(the buffer contents must stay the same). This is not the default to avoid +the misconception that non-blocking SSL_write() behaves like +non-blocking write(). + +=item SSL_MODE_AUTO_RETRY + +Never bother the application with retries if the transport is blocking. +If a renegotiation take place during normal operation, a +L<SSL_read(3)> or L<SSL_write(3)> would return +with -1 and indicate the need to retry with SSL_ERROR_WANT_READ. +In a non-blocking environment applications must be prepared to handle +incomplete read/write operations. +In a blocking environment, applications are not always prepared to +deal with read/write operations returning without success report. The +flag SSL_MODE_AUTO_RETRY will cause read/write operations to only +return after the handshake and successful completion. + +=item SSL_MODE_RELEASE_BUFFERS + +When we no longer need a read buffer or a write buffer for a given SSL, +then release the memory we were using to hold it. +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. + +=item SSL_MODE_ASYNC + +Enable asynchronous processing. TLS I/O operations may indicate a retry with +SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is +used to perform cryptographic operations. See L<SSL_get_error(3)>. + +=back + +=head1 RETURN VALUES + +SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask +after adding B<mode>. + +SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>, L<SSL_get_error(3)> + +=head1 HISTORY + +SSL_MODE_ASYNC was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod new file mode 100644 index 0000000..9546e75 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod @@ -0,0 +1,103 @@ +=pod + +=head1 NAME + +SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_set_msg_callback_arg - install callback for observing protocol messages + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + 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 *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 + +SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to +define a message callback function I<cb> for observing all SSL/TLS +protocol messages (such as handshake messages) that are received or +sent. SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg() +can be used to set argument I<arg> to the callback function, which is +available for arbitrary application use. + +SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify +default settings that will be copied to new B<SSL> objects by +L<SSL_new(3)>. SSL_set_msg_callback() and +SSL_set_msg_callback_arg() modify the actual settings of an B<SSL> +object. Using a B<0> pointer for I<cb> disables the message callback. + +When I<cb> is called by the SSL/TLS library for a protocol message, +the function arguments have the following meaning: + +=over 4 + +=item I<write_p> + +This flag is B<0> when a protocol message has been received and B<1> +when a protocol message has been sent. + +=item I<version> + +The protocol version according to which the protocol message is +interpreted by the library. Currently, this is one of +B<SSL2_VERSION>, B<SSL3_VERSION> and B<TLS1_VERSION> (for SSL 2.0, SSL +3.0 and TLS 1.0, respectively). + +=item I<content_type> + +In the case of SSL 2.0, this is always B<0>. In the case of SSL 3.0 +or TLS 1.0, this is one of the B<ContentType> values defined in the +protocol specification (B<change_cipher_spec(20)>, B<alert(21)>, +B<handshake(22)>; but never B<application_data(23)> because the +callback will only be called for protocol messages). + +=item I<buf>, I<len> + +I<buf> points to a buffer containing the protocol message, which +consists of I<len> bytes. The buffer is no longer valid after the +callback function has returned. + +=item I<ssl> + +The B<SSL> object that received or sent the message. + +=item I<arg> + +The user-defined argument optionally defined by +SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg(). + +=back + +=head1 NOTES + +Protocol messages are passed to the callback function after decryption +and fragment collection where applicable. (Thus record boundaries are +not visible.) + +If processing a received protocol message results in an error, +the callback function may not be called. For example, the callback +function will never see messages that are considered too large to be +processed. + +Due to automatic protocol version negotiation, I<version> is not +necessarily the protocol version used by the sender of the message: If +a TLS 1.0 ClientHello message is received by an SSL 3.0-only server, +I<version> will be B<SSL3_VERSION>. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_new(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod new file mode 100644 index 0000000..241aeb3 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod @@ -0,0 +1,307 @@ +=pod + +=head1 NAME + +SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, +SSL_clear_options, SSL_CTX_get_options, SSL_get_options, +SSL_get_secure_renegotiation_support - manipulate SSL options + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_options(SSL_CTX *ctx, long options); + long SSL_set_options(SSL *ssl, long options); + + long SSL_CTX_clear_options(SSL_CTX *ctx, long options); + long SSL_clear_options(SSL *ssl, long options); + + long SSL_CTX_get_options(SSL_CTX *ctx); + long SSL_get_options(SSL *ssl); + + long SSL_get_secure_renegotiation_support(SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>. +Options already set before are not cleared! + +SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>. +Options already set before are not cleared! + +SSL_CTX_clear_options() clears the options set via bitmask in B<options> +to B<ctx>. + +SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>. + +SSL_CTX_get_options() returns the options set for B<ctx>. + +SSL_get_options() returns the options set for B<ssl>. + +SSL_get_secure_renegotiation_support() indicates whether the peer supports +secure renegotiation. +Note, this is implemented via a macro. + +=head1 NOTES + +The behaviour of the SSL library can be changed by setting several options. +The options are coded as bitmasks and can be combined by a bitwise B<or> +operation (|). + +SSL_CTX_set_options() and SSL_set_options() affect the (external) +protocol behaviour of the SSL library. The (internal) behaviour of +the API can be changed by using the similar +L<SSL_CTX_set_mode(3)> and SSL_set_mode() functions. + +During a handshake, the option settings of the SSL object are used. When +a new SSL object is created from a context using SSL_new(), the current +option setting is copied. Changes to B<ctx> do not affect already created +SSL objects. SSL_clear() does not affect the settings. + +The following B<bug workaround> options are available: + +=over 4 + +=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG + +... + +=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER + +... + +=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG + +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 + +... + +=item SSL_OP_TLS_D5_BUG + +... + +=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS + +Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol +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. + +=back + +It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround +options if compatibility with somewhat broken implementations is +desired. + +The following B<modifying> options are available: + +=over 4 + +=item SSL_OP_TLS_ROLLBACK_BUG + +Disable version rollback attack detection. + +During the client key exchange, the client must send the same information +about acceptable SSL/TLS protocol levels as during the first hello. Some +clients violate this rule by adapting to the server's answer. (Example: +the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server +only understands up to SSLv3. In this case the client must still use the +same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect +to the server's answer and violate the version rollback protection.) + +=item SSL_OP_SINGLE_DH_USE + +Always create a new key when using temporary/ephemeral DH parameters +(see L<SSL_CTX_set_tmp_dh_callback(3)>). +This option must be used to prevent small subgroup attacks, when +the DH parameters were not generated using "strong" primes +(e.g. when using DSA-parameters, see L<dhparam(1)>). +If "strong" primes were used, it is not strictly necessary to generate +a new DH key during each handshake but it is also recommended. +B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever +temporary/ephemeral DH parameters are used. + +=item SSL_OP_EPHEMERAL_RSA + +This option is no longer implemented and is treated as no op. + +=item SSL_OP_CIPHER_SERVER_PREFERENCE + +When choosing a cipher, use the server's preferences instead of the client +preferences. When not set, the SSL server will always follow the clients +preferences. When set, the SSL/TLS server will choose following its +own preferences. + +=item SSL_OP_PKCS1_CHECK_1 + +... + +=item SSL_OP_PKCS1_CHECK_2 + +... + + +=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, +SSL_OP_NO_TLSv1_2, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2 + +These options turn off the SSLv3, TLSv1, TLSv1.1 or TLSv1.2 protocol +versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS, +respectively. +As of OpenSSL 1.1.0, these options are deprecated, use +L<SSL_CTX_set_min_proto_version(3)> and +L<SSL_CTX_set_max_proto_version(3)> instead. + +=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION + +When performing renegotiation as a server, always start a new session +(i.e., session resumption requests are only accepted in the initial +handshake). This option is not needed for clients. + +=item SSL_OP_NO_TICKET + +Normally clients and servers will, where possible, transparently make use +of RFC4507bis tickets for stateless session resumption. + +If this option is set this functionality is disabled and tickets will +not be used by clients or servers. + +=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION + +Allow legacy insecure renegotiation between OpenSSL and unpatched clients or +servers. See the B<SECURE RENEGOTIATION> section for more details. + +=item SSL_OP_LEGACY_SERVER_CONNECT + +Allow legacy insecure renegotiation between OpenSSL and unpatched servers +B<only>: this option is currently set by default. See the +B<SECURE RENEGOTIATION> section for more details. + +=item SSL_OP_NO_ENCRYPT_THEN_MAC + +Normally clients and servers will transparently attempt to negotiate the +RFC7366 Encrypt-then-MAC option on TLS and DTLS connection. + +If this option is set, Encrypt-then-MAC is disabled. Clients will not +propose, and servers will not accept the extension. + +=item SSL_OP_NO_RENEGOTIATION + +Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest +messages, and ignore renegotiation requests via ClientHello. + +=back + +=head1 SECURE RENEGOTIATION + +OpenSSL always attempts to use secure renegotiation as +described in RFC5746. This counters the prefix attack described in +CVE-2009-3555 and elsewhere. + +This attack has far reaching consequences which application writers should be +aware of. In the description below an implementation supporting secure +renegotiation is referred to as I<patched>. A server not supporting secure +renegotiation is referred to as I<unpatched>. + +The following sections describe the operations permitted by OpenSSL's secure +renegotiation implementation. + +=head2 Patched client and server + +Connections and renegotiation are always permitted by OpenSSL implementations. + +=head2 Unpatched client and patched OpenSSL server + +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. + +If the patched OpenSSL server attempts to renegotiate a fatal +B<handshake_failure> alert is sent. This is because the server code may be +unaware of the unpatched nature of the client. + +If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then +renegotiation B<always> succeeds. + +=head2 Patched OpenSSL client and unpatched server. + +If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or +B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections +and renegotiation between patched OpenSSL clients and unpatched servers +succeeds. If neither option is set then initial connections to unpatched +servers will fail. + +The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even +though it has security implications: otherwise it would be impossible to +connect to unpatched servers (i.e. all of them initially) and this is clearly +not acceptable. Renegotiation is permitted because this does not add any +additional security issues: during an attack clients do not see any +renegotiations anyway. + +As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will +B<not> be set by default in a future version of OpenSSL. + +OpenSSL client applications wishing to ensure they can connect to unpatched +servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT> + +OpenSSL client applications that want to ensure they can B<not> connect to +unpatched servers (and thus avoid any security issues) should always B<clear> +B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or +SSL_clear_options(). + +The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and +B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that +B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure +renegotiation between OpenSSL clients and unpatched servers B<only>, while +B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections +and renegotiation between OpenSSL and unpatched clients or servers. + +=head1 RETURN VALUES + +SSL_CTX_set_options() and SSL_set_options() return the new options bitmask +after adding B<options>. + +SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask +after clearing B<options>. + +SSL_CTX_get_options() and SSL_get_options() return the current bitmask. + +SSL_get_secure_renegotiation_support() returns 1 is the peer supports +secure renegotiation and 0 if it does not. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>, +L<SSL_CTX_set_tmp_dh_callback(3)>, +L<SSL_CTX_set_min_proto_version(3)>, +L<dhparam(1)> + +=head1 HISTORY + +The attempt to always try to use secure renegotiation was added in +Openssl 0.9.8m. + +B<SSL_OP_NO_RENEGOTIATION> was added in OpenSSL 1.1.0h. + +=head1 COPYRIGHT + +Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod new file mode 100644 index 0000000..a417508 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, + unsigned int (*callback)(SSL *ssl, const char *hint, + char *identity, unsigned int max_identity_len, + unsigned char *psk, unsigned int max_psk_len)); + void SSL_set_psk_client_callback(SSL *ssl, + unsigned int (*callback)(SSL *ssl, const char *hint, + char *identity, unsigned int max_identity_len, + unsigned char *psk, unsigned int max_psk_len)); + + +=head1 DESCRIPTION + +A client application must provide a callback function which is called +when the client is sending the ClientKeyExchange message to the server. + +The purpose of the callback function is to select the PSK identity and +the pre-shared key to use during the connection setup phase. + +The callback is set using functions SSL_CTX_set_psk_client_callback() +or SSL_set_psk_client_callback(). The callback function is given the +connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint +sent by the server in parameter B<hint>, a buffer B<identity> of +length B<max_identity_len> bytes where the resulting +B<NULL>-terminated identity is to be stored, and a buffer B<psk> of +length B<max_psk_len> bytes where the resulting pre-shared key is to +be stored. + +=head1 NOTES + +Note that parameter B<hint> given to the callback may be B<NULL>. + +=head1 RETURN VALUES + +Return values from the client callback are interpreted as follows: + +On success (callback found a PSK identity and a pre-shared key to use) +the length (> 0) of B<psk> in bytes is returned. + +Otherwise or on errors callback should return 0. In this case +the connection setup fails. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +Copyright 2005 Nokia. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod new file mode 100644 index 0000000..d39d747 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, SSL_get_quiet_shutdown - manipulate shutdown behaviour + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode); + int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx); + + void SSL_set_quiet_shutdown(SSL *ssl, int mode); + int SSL_get_quiet_shutdown(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ctx> to be +B<mode>. SSL objects created from B<ctx> inherit the B<mode> valid at the time +L<SSL_new(3)> is called. B<mode> may be 0 or 1. + +SSL_CTX_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ctx>. + +SSL_set_quiet_shutdown() sets the "quiet shutdown" flag for B<ssl> to be +B<mode>. The setting stays valid until B<ssl> is removed with +L<SSL_free(3)> or SSL_set_quiet_shutdown() is called again. +It is not changed when L<SSL_clear(3)> is called. +B<mode> may be 0 or 1. + +SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>. + +=head1 NOTES + +Normally when a SSL connection is finished, the parties must send out +"close notify" alert messages using L<SSL_shutdown(3)> +for a clean shutdown. + +When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)> +will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. +(L<SSL_shutdown(3)> then behaves like +L<SSL_set_shutdown(3)> called with +SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.) +The session is thus considered to be shutdown, but no "close notify" alert +is sent to the peer. This behaviour violates the TLS standard. + +The default is normal shutdown behaviour as described by the TLS standard. + +=head1 RETURN VALUES + +SSL_CTX_set_quiet_shutdown() and SSL_set_quiet_shutdown() do not return +diagnostic information. + +SSL_CTX_get_quiet_shutdown() and SSL_get_quiet_shutdown return the current +setting. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_shutdown(3)>, +L<SSL_set_shutdown(3)>, L<SSL_new(3)>, +L<SSL_clear(3)>, L<SSL_free(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod new file mode 100644 index 0000000..bea8390 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + +SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead, +SSL_set_read_ahead, SSL_get_read_ahead, +SSL_CTX_get_default_read_ahead +- manage whether to read as many input bytes as possible + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_read_ahead(SSL *s, int yes); + int SSL_get_read_ahead(const SSL *s); + + SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes); + long SSL_CTX_get_read_ahead(SSL_CTX *ctx); + long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_read_ahead() and SSL_set_read_ahead() set whether we should read as +many input bytes as possible (for non-blocking reads) or not. For example if +B<x> bytes are currently required by OpenSSL, but B<y> bytes are available from +the underlying BIO (where B<y> > B<x>), then OpenSSL will read all B<y> bytes +into its buffer (providing that the buffer is large enough) if reading ahead is +on, or B<x> bytes otherwise. The parameter B<yes> or B<m> should be 0 to ensure +reading ahead is off, or non zero otherwise. +SSL_CTX_set_default_read_ahead() is identical to SSL_CTX_set_read_ahead(). + +SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading +ahead has been set or not. + +=head1 NOTES + +These functions have no impact when used with DTLS. The return values for +SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS. Setting +B<read_ahead> can impact the behaviour of the SSL_pending() function +(see L<SSL_pending(3)>). + +=head1 RETURN VALUES + +SSL_get_read_ahead() and SSL_CTX_get_read_ahead() return 0 if reading ahead is off, +and non zero otherwise. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_pending(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod new file mode 100644 index 0000000..577b393 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod @@ -0,0 +1,169 @@ +=pod + +=head1 NAME + +SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data - SSL/TLS security framework + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_security_level(SSL_CTX *ctx, int level); + void SSL_set_security_level(SSL *s, int level); + + int SSL_CTX_get_security_level(const SSL_CTX *ctx); + int SSL_get_security_level(const SSL *s); + + void SSL_CTX_set_security_callback(SSL_CTX *ctx, + int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, + void *other, void *ex)); + + void SSL_set_security_callback(SSL *s, + int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, + void *other, void *ex)); + + int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex); + int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex); + + void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex); + void SSL_set0_security_ex_data(SSL *s, void *ex); + + void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx); + void *SSL_get0_security_ex_data(const SSL *s); + +=head1 DESCRIPTION + +The functions SSL_CTX_set_security_level() and SSL_set_security_level() set +the security level to B<level>. If not set the library default security level +is used. + +The functions SSL_CTX_get_security_level() and SSL_get_security_level() +retrieve the current security level. + +SSL_CTX_set_security_callback(), SSL_set_security_callback(), +SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set +the security callback associated with B<ctx> or B<s>. If not set a default +security callback is used. The meaning of the parameters and the behaviour +of the default callbacks is described below. + +SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(), +SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the +extra data pointer passed to the B<ex> parameter of the callback. This +value is passed to the callback verbatim and can be set to any convenient +application specific value. + +=head1 DEFAULT CALLBACK BEHAVIOUR + +If an application doesn't set its own security callback the default +callback is used. It is intended to provide sane defaults. The meaning +of each level is described below. + +=over 4 + +=item B<Level 0> + +Everything is permitted. This retains compatibility with previous versions of +OpenSSL. + +=item B<Level 1> + +The security level corresponds to a minimum of 80 bits of security. Any +parameters offering below 80 bits of security are excluded. As a result RSA, +DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits +are prohibited. All export ciphersuites are prohibited since they all offer +less than 80 bits of security. SSL version 2 is prohibited. Any ciphersuite +using MD5 for the MAC is also prohibited. + +=item B<Level 2> + +Security level set to 112 bits of security. As a result RSA, DSA and DH keys +shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. +In addition to the level 1 exclusions any ciphersuite using RC4 is also +prohibited. SSL version 3 is also not allowed. Compression is disabled. + +=item B<Level 3> + +Security level set to 128 bits of security. As a result RSA, DSA and DH keys +shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. +In addition to the level 2 exclusions ciphersuites not offering forward +secrecy are prohibited. TLS versions below 1.1 are not permitted. Session +tickets are disabled. + +=item B<Level 4> + +Security level set to 192 bits of security. As a result RSA, DSA and DH keys +shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited. +Ciphersuites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are +not permitted. + +=item B<Level 5> + +Security level set to 256 bits of security. As a result RSA, DSA and DH keys +shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. + +=back + +=head1 APPLICATION DEFINED SECURITY CALLBACKS + +I<Documentation to be provided.> + +=head1 NOTES + +B<WARNING> at this time setting the security level higher than 1 for +general internet use is likely to cause B<considerable> interoperability +issues and is not recommended. This is because the B<SHA1> algorithm +is very widely used in certificates and will be rejected at levels +higher than 1 because it only offers 80 bits of security. + +The default security level can be configured when OpenSSL is compiled by +setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used. + +The security framework disables or reject parameters inconsistent with the +set security level. In the past this was difficult as applications had to set +a number of distinct parameters (supported ciphers, supported curves supported +signature algorithms) to achieve this end and some cases (DH parameter size +for example) could not be checked at all. + +By setting an appropriate security level much of this complexity can be +avoided. + +The bits of security limits affect all relevant parameters including +ciphersuite encryption algorithms, supported ECC curves, supported +signature algorithms, DH parameter sizes, certificate key sizes and +signature algorithms. This limit applies no matter what other custom +settings an application has set: so if the ciphersuite is set to B<ALL> +then only ciphersuites consistent with the security level are permissible. + +See SP800-57 for how the security limits are related to individual +algorithms. + +Some security levels require large key sizes for non-ECC public key +algorithms which can severely degrade performance. For example 256 bits +of security requires the use of RSA keys of at least 15360 bits in size. + +Some restrictions can be gracefully handled: for example ciphersuites +offering insufficient security are not sent by the client and will not +be selected by the server. Other restrictions such as the peer certificate +key size or the DH parameter size will abort the handshake with a fatal +alert. + +Attempts to set certificates or parameters with insufficient security are +also blocked. For example trying to set a certificate using a 512 bit RSA +key using SSL_CTX_use_certificate() at level 1. Applications which do not +check the return values for errors will misbehave: for example it might +appear that a certificate is not set at all because it had been rejected. + +=head1 HISTORY + +These functions were first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod new file mode 100644 index 0000000..b237076 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -0,0 +1,141 @@ +=pod + +=head1 NAME + +SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); + long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_session_cache_mode() enables/disables session caching +by setting the operational mode for B<ctx> to <mode>. + +SSL_CTX_get_session_cache_mode() returns the currently used cache mode. + +=head1 NOTES + +The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. +The sessions can be held in memory for each B<ctx>, if more than one +SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX +object. + +In order to reuse a session, a client must send the session's id to the +server. It can only send exactly one id. The server then either +agrees to reuse the session or it starts a full handshake (to create a new +session). + +A server will look up the session in its internal session storage. If the +session is not found in internal storage or lookups for the internal storage +have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try +the external storage if available. + +Since a client may try to reuse a session intended for use in a different +context, the session id context must be set by the server (see +L<SSL_CTX_set_session_id_context(3)>). + +The following session cache modes and modifiers are available: + +=over 4 + +=item SSL_SESS_CACHE_OFF + +No session caching for client or server takes place. + +=item SSL_SESS_CACHE_CLIENT + +Client sessions are added to the session cache. As there is no reliable way +for the OpenSSL library to know whether a session should be reused or which +session to choose (due to the abstract BIO layer the SSL engine does not +have details about the connection), the application must select the session +to be reused by using the L<SSL_set_session(3)> +function. This option is not activated by default. + +=item SSL_SESS_CACHE_SERVER + +Server sessions are added to the session cache. When a client proposes a +session to be reused, the server looks for the corresponding session in (first) +the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set), +then (second) in the external cache if available. If the session is found, the +server will try to reuse the session. This is the default. + +=item SSL_SESS_CACHE_BOTH + +Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. + +=item SSL_SESS_CACHE_NO_AUTO_CLEAR + +Normally the session cache is checked for expired sessions every +255 connections using the +L<SSL_CTX_flush_sessions(3)> function. Since +this may lead to a delay which cannot be controlled, the automatic +flushing may be disabled and +L<SSL_CTX_flush_sessions(3)> can be called +explicitly by the application. + +=item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP + +By setting this flag, session-resume operations in an SSL/TLS server will not +automatically look up sessions in the internal cache, even if sessions are +automatically stored there. If external session caching callbacks are in use, +this flag guarantees that all lookups are directed to the external cache. +As automatic lookup only applies for SSL/TLS servers, the flag has no effect on +clients. + +=item SSL_SESS_CACHE_NO_INTERNAL_STORE + +Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER, +sessions negotiated in an SSL/TLS handshake may be cached for possible reuse. +Normally a new session is added to the internal cache as well as any external +session caching (callback) that is configured for the SSL_CTX. This flag will +prevent sessions being stored in the internal cache (though the application can +add them manually using L<SSL_CTX_add_session(3)>). Note: +in any SSL/TLS servers where external caching is configured, any successful +session lookups in the external cache (ie. for session-resume requests) would +normally be copied into the local cache before processing continues - this flag +prevents these additions to the internal cache as well. + +=item SSL_SESS_CACHE_NO_INTERNAL + +Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and +SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time. + + +=back + +The default mode is SSL_SESS_CACHE_SERVER. + +=head1 RETURN VALUES + +SSL_CTX_set_session_cache_mode() returns the previously set cache mode. + +SSL_CTX_get_session_cache_mode() returns the currently set cache mode. + + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_set_session(3)>, +L<SSL_session_reused(3)>, +L<SSL_CTX_add_session(3)>, +L<SSL_CTX_sess_number(3)>, +L<SSL_CTX_sess_set_cache_size(3)>, +L<SSL_CTX_sess_set_get_cb(3)>, +L<SSL_CTX_set_session_id_context(3)>, +L<SSL_CTX_set_timeout(3)>, +L<SSL_CTX_flush_sessions(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod new file mode 100644 index 0000000..a873b03 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod @@ -0,0 +1,92 @@ +=pod + +=head1 NAME + +SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only) + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + +=head1 DESCRIPTION + +SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length +B<sid_ctx_len> within which a session can be reused for the B<ctx> object. + +SSL_set_session_id_context() sets the context B<sid_ctx> of length +B<sid_ctx_len> within which a session can be reused for the B<ssl> object. + +=head1 NOTES + +Sessions are generated within a certain context. When exporting/importing +sessions with B<i2d_SSL_SESSION>/B<d2i_SSL_SESSION> it would be possible, +to re-import a session generated from another context (e.g. another +application), which might lead to malfunctions. Therefore each application +must set its own session id context B<sid_ctx> which is used to distinguish +the contexts and is stored in exported sessions. The B<sid_ctx> can be +any kind of binary data with a given length, it is therefore possible +to use e.g. the name of the application and/or the hostname and/or service +name ... + +The session id context becomes part of the session. The session id context +is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and +SSL_set_session_id_context() functions are therefore only useful on the +server side. + +OpenSSL clients will check the session id context returned by the server +when reusing a session. + +The maximum length of the B<sid_ctx> is limited to +B<SSL_MAX_SSL_SESSION_ID_LENGTH>. + +=head1 WARNINGS + +If the session id context is not set on an SSL/TLS server and client +certificates are used, stored sessions +will not be reused but a fatal error will be flagged and the handshake +will fail. + +If a server returns a different session id context to an OpenSSL client +when reusing a session, an error will be flagged and the handshake will +fail. OpenSSL servers will always return the correct session id context, +as an OpenSSL server checks the session id context itself before reusing +a session as described above. + +=head1 RETURN VALUES + +SSL_CTX_set_session_id_context() and SSL_set_session_id_context() +return the following values: + +=over 4 + +=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 Z<>1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod new file mode 100644 index 0000000..accf5af --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod @@ -0,0 +1,132 @@ +=pod + +=head1 NAME + +SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment, +SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment, +SSL_CTX_set_max_pipelines, SSL_set_max_pipelines, +SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control +fragment sizes and pipelining operations + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long); + long SSL_set_max_send_fragment(SSL *ssl, long m); + + long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m); + long SSL_set_max_pipelines(SSL_CTX *ssl, long m); + + long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m); + long SSL_set_split_send_fragment(SSL *ssl, long m); + + void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len); + void SSL_set_default_read_buffer_len(SSL *s, size_t len); + +=head1 DESCRIPTION + +Some engines are able to process multiple simultaneous crypto operations. This +capability could be utilised to parallelise the processing of a single +connection. For example a single write can be split into multiple records and +each one encrypted independently and in parallel. Note: this will only work in +TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This +capability is known as "pipelining" within OpenSSL. + +In order to benefit from the pipelining capability. You need to have an engine +that provides ciphers that support this. The OpenSSL "dasync" engine provides +AES128-SHA based ciphers that have this capability. However these are for +development and test purposes only. + +SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the +B<max_send_fragment> parameter for SSL_CTX and SSL objects respectively. This +value restricts the amount of plaintext bytes that will be sent in any one +SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These +functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH. + +SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number +of pipelines that will be used at any one time. This value applies to both +"read" pipelining and "write" pipelining. By default only one pipeline will be +used (i.e. normal non-parallel operation). The number of pipelines set must be +in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also +automatically turn on "read_ahead" (see L<SSL_CTX_set_read_ahead(3)>). This is +explained further below. OpenSSL will only every use more than one pipeline if +a ciphersuite is negotiated that uses a pipeline capable cipher provided by an +engine. + +Pipelining operates slightly differently for reading encrypted data compared to +writing encrypted data. SSL_CTX_set_split_send_fragment() and +SSL_set_split_send_fragment() define how data is split up into pipelines when +writing encrypted data. The number of pipelines used will be determined by the +amount of data provided to the SSL_write() call divided by +B<split_send_fragment>. + +For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4 +then: + +SSL_write called with 0-2000 bytes == 1 pipeline used + +SSL_write called with 2001-4000 bytes == 2 pipelines used + +SSL_write called with 4001-6000 bytes == 3 pipelines used + +SSL_write called with 6001+ bytes == 4 pipelines used + +B<split_send_fragment> must always be less than or equal to +B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>. +This will mean that the same number of records will always be created as would +have been created in the non-parallel case, although the data will be +apportioned differently. In the parallel case data will be spread equally +between the pipelines. + +Read pipelining is controlled in a slightly different way than with write +pipelining. While reading we are constrained by the number of records that the +peer (and the network) can provide to us in one go. The more records we can get +in one go the more opportunity we have to parallelise the processing. As noted +above when setting B<max_pipelines> to a value greater than one, B<read_ahead> +is automatically set. The B<read_ahead> parameter causes OpenSSL to attempt to +read as much data into the read buffer as the network can provide and will fit +into the buffer. Without this set data is read into the read buffer one record +at a time. The more data that can be read, the more opportunity there is for +parallelising the processing at the cost of increased memory overhead per +connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending() +function (see L<SSL_pending(3)>). + +The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() +functions control the size of the read buffer that will be used. The B<len> +parameter sets the size of the buffer. The value will only be used if it is +greater than the default that would have been used anyway. The normal default +value depends on a number of factors but it will be at least +SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes. + +=head1 RETURN VALUES + +All non-void functions return 1 on success and 0 on failure. + +=head1 NOTES + +With the exception of SSL_CTX_set_default_read_buffer_len() and +SSL_set_default_read_buffer_len() all these functions are implemented using +macros. + +=head1 HISTORY + +The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(), +SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(), +SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() +functions were added in OpenSSL 1.1.0. + +=head1 SEE ALSO + +L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod new file mode 100644 index 0000000..22c0370 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method +- choose a new TLS/SSL method + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *method); + int SSL_set_ssl_method(SSL *s, const SSL_METHOD *method); + const SSL_METHOD *SSL_get_ssl_method(SSL *ssl); + +=head1 DESCRIPTION + +SSL_CTX_set_ssl_version() sets a new default TLS/SSL B<method> for SSL objects +newly created from this B<ctx>. SSL objects already created with +L<SSL_new(3)> are not affected, except when +L<SSL_clear(3)> is being called. + +SSL_set_ssl_method() sets a new TLS/SSL B<method> for a particular B<ssl> +object. It may be reset, when SSL_clear() is called. + +SSL_get_ssl_method() returns a function pointer to the TLS/SSL method +set in B<ssl>. + +=head1 NOTES + +The available B<method> choices are described in +L<SSL_CTX_new(3)>. + +When L<SSL_clear(3)> is called and no session is connected to +an SSL object, the method of the SSL object is reset to the method currently +set in the corresponding SSL_CTX object. + +=head1 RETURN VALUES + +The following return values can occur for SSL_CTX_set_ssl_version() +and SSL_set_ssl_method(): + +=over 4 + +=item Z<>0 + +The new choice failed, check the error stack to find out the reason. + +=item Z<>1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<SSL_CTX_new(3)>, L<SSL_new(3)>, +L<SSL_clear(3)>, L<ssl(3)>, +L<SSL_set_connect_state(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod new file mode 100644 index 0000000..470efdf --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for session caching + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_CTX_set_timeout(SSL_CTX *ctx, long t); + long SSL_CTX_get_timeout(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_timeout() sets the timeout for newly created sessions for +B<ctx> to B<t>. The timeout value B<t> must be given in seconds. + +SSL_CTX_get_timeout() returns the currently set timeout value for B<ctx>. + +=head1 NOTES + +Whenever a new session is created, it is assigned a maximum lifetime. This +lifetime is specified by storing the creation time of the session and the +timeout value valid at this time. If the actual time is later than creation +time plus timeout, the session is not reused. + +Due to this realization, all sessions behave according to the timeout value +valid at the time of the session negotiation. Changes of the timeout value +do not affect already established sessions. + +The expiration time of a single session can be modified using the +L<SSL_SESSION_get_time(3)> family of functions. + +Expired sessions are removed from the internal session cache, whenever +L<SSL_CTX_flush_sessions(3)> is called, either +directly by the application or automatically (see +L<SSL_CTX_set_session_cache_mode(3)>) + +The default value for session timeout is decided on a per protocol +basis, see L<SSL_get_default_timeout(3)>. +All currently supported protocols have the same default timeout value +of 300 seconds. + +=head1 RETURN VALUES + +SSL_CTX_set_timeout() returns the previously set timeout value. + +SSL_CTX_get_timeout() returns the currently set timeout value. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_get_time(3)>, +L<SSL_CTX_flush_sessions(3)>, +L<SSL_get_default_timeout(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod new file mode 100644 index 0000000..c12ff0e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod @@ -0,0 +1,125 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tlsext_status_cb, +SSL_CTX_get_tlsext_status_cb, +SSL_CTX_set_tlsext_status_arg, +SSL_CTX_get_tlsext_status_arg, +SSL_CTX_set_tlsext_status_type, +SSL_CTX_get_tlsext_status_type, +SSL_set_tlsext_status_type, +SSL_get_tlsext_status_type, +SSL_get_tlsext_status_ocsp_resp, +SSL_set_tlsext_status_ocsp_resp +- OCSP Certificate Status Request functions + +=head1 SYNOPSIS + + #include <openssl/tls1.h> + + long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, + int (*callback)(SSL *, void *)); + long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx, + int (**callback)(SSL *, void *)); + + long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg); + long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg); + + long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type); + long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx); + + long SSL_set_tlsext_status_type(SSL *s, int type); + long SSL_get_tlsext_status_type(SSL *s); + + long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp); + long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len); + +=head1 DESCRIPTION + +A client application may request that a server send back an OCSP status response +(also known as OCSP stapling). To do so the client should call the +SSL_CTX_set_tlsext_status_type() function prior to the creation of any SSL +objects. Alternatively an application can call the SSL_set_tlsext_status_type() +function on an individual SSL object prior to the start of the handshake. +Currently the only supported type is B<TLSEXT_STATUSTYPE_ocsp>. This value +should be passed in the B<type> argument. Calling +SSL_CTX_get_tlsext_status_type() will return the type B<TLSEXT_STATUSTYPE_ocsp> +previously set via SSL_CTX_set_tlsext_status_type() or -1 if not set. + +The client should additionally provide a callback function to decide what to do +with the returned OCSP response by calling SSL_CTX_set_tlsext_status_cb(). The +callback function should determine whether the returned OCSP response is +acceptable or not. The callback will be passed as an argument the value +previously set via a call to SSL_CTX_set_tlsext_status_arg(). Note that the +callback will not be called in the event of a handshake where session resumption +occurs (because there are no Certificates exchanged in such a handshake). +The callback previously set via SSL_CTX_set_tlsext_status_cb() can be retrieved +by calling SSL_CTX_get_tlsext_status_cb(), and the argument by calling +SSL_CTX_get_tlsext_status_arg(). + +On the client side SSL_get_tlsext_status_type() can be used to determine whether +the client has previously called SSL_set_tlsext_status_type(). It will return +B<TLSEXT_STATUSTYPE_ocsp> if it has been called or -1 otherwise. On the server +side SSL_get_tlsext_status_type() can be used to determine whether the client +requested OCSP stapling. If the client requested it then this function will +return B<TLSEXT_STATUSTYPE_ocsp>, or -1 otherwise. + +The response returned by the server can be obtained via a call to +SSL_get_tlsext_status_ocsp_resp(). The value B<*resp> will be updated to point +to the OCSP response data and the return value will be the length of that data. +Typically a callback would obtain an OCSP_RESPONSE object from this data via a +call to the d2i_OCSP_RESPONSE() function. If the server has not provided any +response data then B<*resp> will be NULL and the return value from +SSL_get_tlsext_status_ocsp_resp() will be -1. + +A server application must also call the SSL_CTX_set_tlsext_status_cb() function +if it wants to be able to provide clients with OCSP Certificate Status +responses. Typically the server callback would obtain the server certificate +that is being sent back to the client via a call to SSL_get_certificate(); +obtain the OCSP response to be sent back; and then set that response data by +calling SSL_set_tlsext_status_ocsp_resp(). A pointer to the response data should +be provided in the B<resp> argument, and the length of that data should be in +the B<len> argument. + +=head1 RETURN VALUES + +The callback when used on the client side should return a negative value on +error; 0 if the response is not acceptable (in which case the handshake will +fail) or a positive value if it is acceptable. + +The callback when used on the server side should return with either +SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be +returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be +returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has +occurred). + +SSL_CTX_set_tlsext_status_cb(), SSL_CTX_set_tlsext_status_arg(), +SSL_CTX_set_tlsext_status_type(), SSL_set_tlsext_status_type() and +SSL_set_tlsext_status_ocsp_resp() return 0 on error or 1 on success. + +SSL_CTX_get_tlsext_status_type() returns the value previously set by +SSL_CTX_set_tlsext_status_type(), or -1 if not set. + +SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data +or -1 if there is no OCSP response data. + +SSL_get_tlsext_status_type() returns B<TLSEXT_STATUSTYPE_ocsp> on the client +side if SSL_set_tlsext_status_type() was previously called, or on the server +side if the client requested OCSP stapling. Otherwise -1 is returned. + +=head1 HISTORY + +SSL_get_tlsext_status_type(), SSL_CTX_get_tlsext_status_type() and +SSL_CTX_set_tlsext_status_type() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod new file mode 100644 index 0000000..34d8ce9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod @@ -0,0 +1,198 @@ +=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 function 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 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 retrieval 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 arbitrary 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 B<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(3)>. The hmac context can be set using +L<HMAC_Init_ex(3)>. + +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 retrieve 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 retrieved parameters and the initialization vector +I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The I<hctx> needs to be +set using L<HMAC_Init_ex(3)>. + +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 argument 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 negotiating 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 +negotiation 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 negotiation had occurred. + +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 Implementation: + 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)>, L<SSL_set_session(3)>, +L<SSL_session_reused(3)>, +L<SSL_CTX_add_session(3)>, +L<SSL_CTX_sess_number(3)>, +L<SSL_CTX_sess_set_get_cb(3)>, +L<SSL_CTX_set_session_id_context(3)>, + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod new file mode 100644 index 0000000..fbfb8cb --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod @@ -0,0 +1,137 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral key exchange + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, + 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, + DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); + long SSL_set_tmp_dh(SSL *ssl, DH *dh) + +=head1 DESCRIPTION + +SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be +used when a DH parameters are required to B<tmp_dh_callback>. +The callback is inherited by all B<ssl> objects created from B<ctx>. + +SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. +The key is inherited by all B<ssl> objects created from B<ctx>. + +SSL_set_tmp_dh_callback() sets the callback only for B<ssl>. + +SSL_set_tmp_dh() sets the parameters only for B<ssl>. + +These functions apply to SSL/TLS servers only. + +=head1 NOTES + +When using a cipher with RSA authentication, an ephemeral DH key exchange +can take place. Ciphers with DSA keys always use ephemeral DH keys as well. +In these cases, the session data are negotiated using the +ephemeral/temporary DH key and the key supplied and certified +by the certificate chain is only used for signing. +Anonymous ciphers (without a permanent server key) also use ephemeral DH keys. + +Using ephemeral DH key exchange yields forward secrecy, as the connection +can only be decrypted, when the DH key is known. By generating a temporary +DH key inside the server application that is lost when the application +is left, it becomes impossible for an attacker to decrypt past sessions, +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. + +As generating DH parameters is extremely time consuming, an application +should not generate the parameters on the fly but supply the parameters. +DH parameters can be reused, as the actual key is newly generated during +the negotiation. The risk in reusing DH parameters is that an attacker +may specialize on a very often used DH group. Applications should therefore +generate their own DH parameters during the installation process using the +openssl L<dhparam(1)> application. This application +guarantees that "strong" primes are used. + +Files dh2048.pem, and dh4096.pem in the 'apps' directory of the 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 +L<dhparam(1)> application. Generation of custom DH +parameters during installation should still be preferred to stop an +attacker from specializing on a commonly used group. File dh1024.pem +contains old parameters that must not be used by applications. + +An application may either directly specify the DH parameters or +can supply the DH parameters via a callback function. + +Previous versions of the callback used B<is_export> and B<keylength> +parameters to control parameter generation for export and non-export +cipher suites. Modern servers that do not support export ciphersuites +are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use +the callback but ignore B<keylength> and B<is_export> and simply +supply at least 2048-bit parameters in the callback. + +=head1 EXAMPLES + +Setup DH parameters with a key length of 2048 bits. (Error handling +partly left out.) + + Command-line parameter generation: + $ openssl dhparam -out dh_param_2048.pem 2048 + + Code for setting up parameters during server initialization: + + ... + SSL_CTX ctx = SSL_CTX_new(); + ... + + /* Set up ephemeral DH parameters. */ + DH *dh_2048 = NULL; + FILE *paramfile; + paramfile = fopen("dh_param_2048.pem", "r"); + if (paramfile) { + dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); + fclose(paramfile); + } else { + /* Error. */ + } + if (dh_2048 == NULL) { + /* Error. */ + } + if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { + /* Error. */ + } + ... + +=head1 RETURN VALUES + +SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return +diagnostic output. + +SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 +on failure. Check the error queue to find out the reason of failure. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>, +L<SSL_CTX_set_options(3)>, +L<ciphers(1)>, L<dhparam(1)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod new file mode 100644 index 0000000..7993498 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod @@ -0,0 +1,307 @@ +=pod + +=head1 NAME + +SSL_get_ex_data_X509_STORE_CTX_idx, +SSL_CTX_set_verify, SSL_set_verify, +SSL_CTX_set_verify_depth, SSL_set_verify_depth, +SSL_verify_cb +- set peer certificate verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback); + void SSL_set_verify(SSL *s, int mode, SSL_verify_cb verify_callback); + SSL_get_ex_data_X509_STORE_CTX_idx(void); + + void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth); + void SSL_set_verify_depth(SSL *s, int depth); + + + typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and +specifies the B<verify_callback> function to be used. If no callback function +shall be specified, the NULL pointer can be used for B<verify_callback>. + +SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and +specifies the B<verify_callback> function to be used. If no callback function +shall be specified, the NULL pointer can be used for B<verify_callback>. In +this case last B<verify_callback> set specifically for this B<ssl> remains. If +no special B<callback> was set before, the default callback for the underlying +B<ctx> is used, that was valid at the time B<ssl> was created with +L<SSL_new(3)>. Within the callback function, +B<SSL_get_ex_data_X509_STORE_CTX_idx> can be called to get the data index +of the current SSL object that is doing the verification. + +SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain +verification that shall be allowed for B<ctx>. + +SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain +verification that shall be allowed for B<ssl>. + +=head1 NOTES + +The verification of certificates can be controlled by a set of logically +or'ed B<mode> flags: + +=over 4 + +=item SSL_VERIFY_NONE + +B<Server mode:> the server will not send a client certificate request to the +client, so the client will not send a certificate. + +B<Client mode:> if not using an anonymous cipher (by default disabled), the +server will send a certificate which will be checked. The result of the +certificate verification process can be checked after the TLS/SSL handshake +using the L<SSL_get_verify_result(3)> function. +The handshake will be continued regardless of the verification result. + +=item SSL_VERIFY_PEER + +B<Server mode:> the server sends a client certificate request to the client. +The certificate returned (if any) is checked. If the verification process +fails, the TLS/SSL handshake is +immediately terminated with an alert message containing the reason for +the verification failure. +The behaviour can be controlled by the additional +SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. + +B<Client mode:> the server certificate is verified. If the verification process +fails, the TLS/SSL handshake is +immediately terminated with an alert message containing the reason for +the verification failure. If no server certificate is sent, because an +anonymous cipher is used, SSL_VERIFY_PEER is ignored. + +=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT + +B<Server mode:> if the client did not return a certificate, the TLS/SSL +handshake is immediately terminated with a "handshake failure" alert. +This flag must be used together with SSL_VERIFY_PEER. + +B<Client mode:> ignored + +=item SSL_VERIFY_CLIENT_ONCE + +B<Server mode:> only request a client certificate on the initial TLS/SSL +handshake. Do not ask for a client certificate again in case of a +renegotiation. This flag must be used together with SSL_VERIFY_PEER. + +B<Client mode:> ignored + +=back + +If the B<mode> is SSL_VERIFY_NONE none of the other flags may be set. + +The actual verification procedure is performed either using the built-in +verification procedure or using another application provided verification +function set with +L<SSL_CTX_set_cert_verify_callback(3)>. +The following descriptions apply in the case of the built-in procedure. An +application provided procedure also has access to the verify depth information +and the verify_callback() function, but the way this information is used +may be different. + +SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set a limit on the +number of certificates between the end-entity and trust-anchor certificates. +Neither the +end-entity nor the trust-anchor certificates count against B<depth>. If the +certificate chain needed to reach a trusted issuer is longer than B<depth+2>, +X509_V_ERR_CERT_CHAIN_TOO_LONG 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, 2 and 3 (0 being the end-entity and 3 the +trust-anchor). +The default depth limit is 100, +allowing for the peer certificate, at most 100 intermediate CA certificates and +a final trust anchor certificate. + +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 +receives two arguments: B<preverify_ok> indicates, whether the verification of +the certificate in question was passed (preverify_ok=1) or not +(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used +for the certificate chain verification. + +The certificate chain is checked starting with the deepest nesting level +(the root CA certificate) and worked upward to the peer's certificate. +At each level signatures and issuer attributes are checked. Whenever +a verification error is found, the error number is stored in B<x509_ctx> +and B<verify_callback> is called with B<preverify_ok>=0. By applying +X509_CTX_store_* functions B<verify_callback> can locate the certificate +in question and perform additional steps (see EXAMPLES). If no error is +found for a certificate, B<verify_callback> is called with B<preverify_ok>=1 +before advancing to the next level. + +The return value of B<verify_callback> controls the strategy of the further +verification process. If B<verify_callback> returns 0, the verification +process is immediately stopped with "verification failed" state. If +SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and +the TLS/SSL handshake is terminated. If B<verify_callback> returns 1, +the verification process is continued. If B<verify_callback> always returns +1, the TLS/SSL handshake will not be terminated with respect to verification +failures and the connection will be established. The calling process can +however retrieve the error code of the last verification error using +L<SSL_get_verify_result(3)> or by maintaining its +own error storage managed by B<verify_callback>. + +If no B<verify_callback> is specified, the default callback will be used. +Its return value is identical to B<preverify_ok>, so that any verification +failure will lead to a termination of the TLS/SSL handshake with an +alert message, if SSL_VERIFY_PEER is set. + +=head1 BUGS + +In client mode, it is not checked whether the SSL_VERIFY_PEER flag +is set, but whether any flags are set. This can lead to +unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as +required. + +=head1 RETURN VALUES + +The SSL*_set_verify*() functions do not provide diagnostic information. + +=head1 EXAMPLES + +The following code sequence realizes an example B<verify_callback> function +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; information about the certificate chain +is printed on request. +The example is realized for a server that does allow but not require client +certificates. + +The example makes use of the ex_data technique to store application data +into/retrieve application data from the SSL structure +(see L<CRYPTO_get_ex_new_index(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>). + + ... + typedef struct { + int verbose_mode; + int verify_depth; + int always_continue; + } mydata_t; + int mydata_index; + ... + static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) + { + char buf[256]; + X509 *err_cert; + int err, depth; + SSL *ssl; + mydata_t *mydata; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + /* + * Retrieve the pointer to the SSL of the connection currently treated + * and the application specific data stored into the SSL object. + */ + ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); + mydata = SSL_get_ex_data(ssl, mydata_index); + + X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); + + /* + * Catch a too long certificate chain. The depth limit set using + * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so + * that whenever the "depth>verify_depth" condition is met, we + * have violated the limit and want to log this error condition. + * We must do it here, because the CHAIN_TOO_LONG error would not + * be found explicitly; only errors introduced by cutting off the + * additional certificates would be logged. + */ + if (depth > mydata->verify_depth) { + preverify_ok = 0; + err = X509_V_ERR_CERT_CHAIN_TOO_LONG; + X509_STORE_CTX_set_error(ctx, err); + } + if (!preverify_ok) { + printf("verify error:num=%d:%s:depth=%d:%s\n", err, + X509_verify_cert_error_string(err), depth, buf); + } + else if (mydata->verbose_mode) + { + printf("depth=%d:%s\n", depth, buf); + } + + /* + * At this point, err contains the last verification error. We can use + * it for something special + */ + if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) + { + X509_NAME_oneline(X509_get_issuer_name(err_cert), buf, 256); + printf("issuer= %s\n", buf); + } + + if (mydata->always_continue) + return 1; + else + return preverify_ok; + } + ... + + mydata_t mydata; + + ... + mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); + + ... + SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, + verify_callback); + + /* + * Let the verify_callback catch the verify_depth error so that we get + * an appropriate error in the logfile. + */ + SSL_CTX_set_verify_depth(verify_depth + 1); + + /* + * Set up the SSL specific data into "mydata" and store it into th SSL + * structure. + */ + mydata.verify_depth = verify_depth; ... + SSL_set_ex_data(ssl, mydata_index, &mydata); + + ... + SSL_accept(ssl); /* check of success left out for clarity */ + if (peer = SSL_get_peer_certificate(ssl)) + { + if (SSL_get_verify_result(ssl) == X509_V_OK) + { + /* The client sent a certificate which verified OK */ + } + } + +=head1 SEE ALSO + +L<ssl(7)>, L<SSL_new(3)>, +L<SSL_CTX_get_verify_mode(3)>, +L<SSL_get_verify_result(3)>, +L<SSL_CTX_load_verify_locations(3)>, +L<SSL_get_peer_certificate(3)>, +L<SSL_CTX_set_cert_verify_callback(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>, +L<CRYPTO_get_ex_new_index(3)> + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod new file mode 100644 index 0000000..c645f58 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod @@ -0,0 +1,180 @@ +=pod + +=head1 NAME + +SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, +SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, +SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, +SSL_use_certificate_chain_file, +SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, +SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, +SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, +SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, +SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, +SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key +- load certificate and key data + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x); + int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d); + int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type); + int SSL_use_certificate(SSL *ssl, X509 *x); + int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len); + int SSL_use_certificate_file(SSL *ssl, const char *file, int type); + + int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); + int SSL_use_certificate_chain_file(SSL *ssl, const char *file); + + int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey); + int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d, + long len); + int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type); + int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); + int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len); + int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type); + int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); + int SSL_use_PrivateKey_ASN1(int pk, SSL *ssl, unsigned char *d, long len); + int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type); + int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); + int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len); + int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type); + + int SSL_CTX_check_private_key(const SSL_CTX *ctx); + int SSL_check_private_key(const SSL *ssl); + +=head1 DESCRIPTION + +These functions load the certificates and private keys into the SSL_CTX +or SSL object, respectively. + +The SSL_CTX_* class of functions loads the certificates and keys into the +SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl> +created from B<ctx> with L<SSL_new(3)> by copying, so that +changes applied to B<ctx> do not propagate to already existing SSL objects. + +The SSL_* class of functions only loads certificates and keys into a +specific SSL object. The specific information is kept, when +L<SSL_clear(3)> is called for this SSL object. + +SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>, +SSL_use_certificate() loads B<x> into B<ssl>. The rest of the +certificates needed to form the complete certificate chain can be +specified using the +L<SSL_CTX_add_extra_chain_cert(3)> +function. + +SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from +the memory location B<d> (with length B<len>) into B<ctx>, +SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>. + +SSL_CTX_use_certificate_file() loads the first certificate stored in B<file> +into B<ctx>. The formatting B<type> of the certificate must be specified +from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. +SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>. +See the NOTES section on why SSL_CTX_use_certificate_chain_file() +should be preferred. + +SSL_CTX_use_certificate_chain_file() loads a certificate chain from +B<file> into B<ctx>. The certificates must be in PEM format and must +be sorted starting with the subject's certificate (actual client or server +certificate), followed by intermediate CA certificates if applicable, and +ending at the highest level (root) CA. SSL_use_certificate_chain_file() is +similar except it loads the certificate chain into B<ssl>. + +SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>. +SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA +to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>; +SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>. +If a certificate has already been set and the private does not belong +to the certificate an error is returned. To change a certificate, private +key pair the new certificate needs to be set with SSL_use_certificate() +or SSL_CTX_use_certificate() before setting the private key with +SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey(). + + +SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk> +stored at memory location B<d> (length B<len>) to B<ctx>. +SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA +stored at memory location B<d> (length B<len>) to B<ctx>. +SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private +key to B<ssl>. + +SSL_CTX_use_PrivateKey_file() adds the first private key found in +B<file> to B<ctx>. The formatting B<type> of the certificate must be specified +from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. +SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in +B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found +in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private +RSA key found to B<ssl>. + +SSL_CTX_check_private_key() checks the consistency of a private key with +the corresponding certificate loaded into B<ctx>. If more than one +key/certificate pair (RSA/DSA) is installed, the last item installed will +be checked. If e.g. the last item was a RSA certificate or key, the RSA +key/certificate pair will be checked. SSL_check_private_key() performs +the same check for B<ssl>. If no key/certificate was explicitly added for +this B<ssl>, the last item added into B<ctx> will be checked. + +=head1 NOTES + +The internal certificate store of OpenSSL can hold several private +key/certificate pairs at a time. The certificate used depends on the +cipher selected, see also L<SSL_CTX_set_cipher_list(3)>. + +When reading certificates and private keys from file, files of type +SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain +one certificate or private key, consequently +SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting. +Files of type SSL_FILETYPE_PEM can contain more than one item. + +SSL_CTX_use_certificate_chain_file() adds the first certificate found +in the file to the certificate store. The other certificates are added +to the store of chain certificates using L<SSL_CTX_add1_chain_cert(3)>. Note: versions of OpenSSL before 1.0.2 only had a single +certificate chain store for all certificate types, OpenSSL 1.0.2 and later +have a separate chain store for each type. SSL_CTX_use_certificate_chain_file() +should be used instead of the SSL_CTX_use_certificate_file() function in order +to allow the use of complete certificate chains even when no trusted CA +storage is used or when the CA issuing the certificate shall not be added to +the trusted CA storage. + +If additional certificates are needed to complete the chain during the +TLS negotiation, CA certificates are additionally looked up in the +locations of trusted CA certificates, see +L<SSL_CTX_load_verify_locations(3)>. + +The private keys loaded from file can be encrypted. In order to successfully +load encrypted keys, a function returning the passphrase must have been +supplied, see +L<SSL_CTX_set_default_passwd_cb(3)>. +(Certificate files might be encrypted as well from the technical point +of view, it however does not make sense as the data in the certificate +is considered public anyway.) + +=head1 RETURN VALUES + +On success, the functions return 1. +Otherwise check out the error stack to find out the reason. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_new(3)>, L<SSL_clear(3)>, +L<SSL_CTX_load_verify_locations(3)>, +L<SSL_CTX_set_default_passwd_cb(3)>, +L<SSL_CTX_set_cipher_list(3)>, +L<SSL_CTX_set_client_CA_list(3)>, +L<SSL_CTX_set_client_cert_cb(3)>, +L<SSL_CTX_add_extra_chain_cert(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod new file mode 100644 index 0000000..753074a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint, +SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK +identity hint to use + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); + int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); + + void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, + unsigned int (*callback)(SSL *ssl, const char *identity, + unsigned char *psk, int max_psk_len)); + void SSL_set_psk_server_callback(SSL *ssl, + unsigned int (*callback)(SSL *ssl, const char *identity, + unsigned char *psk, int max_psk_len)); + + +=head1 DESCRIPTION + +SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK +identity hint B<hint> to SSL context object +B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated +PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint> +is B<NULL> the current hint from B<ctx> or B<ssl> is deleted. + +In the case where PSK identity hint is B<NULL>, the server +does not send the ServerKeyExchange message to the client. + +A server application must provide a callback function which is called +when the server receives the ClientKeyExchange message from the +client. The purpose of the callback function is to validate the +received PSK identity and to fetch the pre-shared key used during the +connection setup phase. The callback is set using functions +SSL_CTX_set_psk_server_callback() or +SSL_set_psk_server_callback(). The callback function is given the +connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent +by the client in parameter B<identity>, and a buffer B<psk> of length +B<max_psk_len> bytes where the pre-shared key is to be stored. + + +=head1 RETURN VALUES + +SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return +1 on success, 0 otherwise. + +Return values from the server callback are interpreted as follows: + +=over 4 + +=item Z<>0 + +PSK identity was not found. An "unknown_psk_identity" alert message +will be sent and the connection setup fails. + +=item E<gt>0 + +PSK identity was found and the server callback has provided the PSK +successfully in parameter B<psk>. Return value is the length of +B<psk> in bytes. It is an error to return a value greater than +B<max_psk_len>. + +If the PSK identity was not found but the callback instructs the +protocol to continue anyway, the callback must provide some random +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. + +=back + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +Copyright 2005 Nokia. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod new file mode 100644 index 0000000..bd496ff --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +SSL_CTX_use_serverinfo, SSL_CTX_use_serverinfo_file - use serverinfo extension + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo, + size_t serverinfo_length); + + int SSL_CTX_use_serverinfo_file(SSL_CTX *ctx, const char *file); + +=head1 DESCRIPTION + +These functions load "serverinfo" TLS ServerHello Extensions into the SSL_CTX. +A "serverinfo" extension is returned in response to an empty ClientHello +Extension. + +SSL_CTX_use_serverinfo() loads one or more serverinfo extensions from +a byte array into B<ctx>. The extensions must be concatenated into a +sequence of bytes. Each extension must consist of a 2-byte Extension Type, +a 2-byte length, and then length bytes of extension_data. + +SSL_CTX_use_serverinfo_file() loads one or more serverinfo extensions from +B<file> into B<ctx>. The extensions must be in PEM format. Each extension +must consist of a 2-byte Extension Type, a 2-byte length, and then length +bytes of extension_data. Each PEM extension name must begin with the phrase +"BEGIN SERVERINFO FOR ". + +If more than one certificate (RSA/DSA) is installed using +SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the +last certificate installed. If e.g. the last item was a RSA certificate, the +loaded serverinfo extension data will be loaded for that certificate. To +use the serverinfo extension for multiple certificates, +SSL_CTX_use_serverinfo() needs to be called multiple times, once B<after> +each time a certificate is loaded. + +=head1 RETURN VALUES + +On success, the functions return 1. +On failure, the functions return 0. Check out the error stack to find out +the reason. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod new file mode 100644 index 0000000..5bea785 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod @@ -0,0 +1,78 @@ +=pod + +=head1 NAME + +SSL_SESSION_new, +SSL_SESSION_up_ref, +SSL_SESSION_free - create, free and manage SSL_SESSION structures + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_SESSION *SSL_SESSION_new(void); + int SSL_SESSION_up_ref(SSL_SESSION *ses); + void SSL_SESSION_free(SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_SESSION_new() creates a new SSL_SESSION structure and returns a pointer to +it. + +SSL_SESSION_up_ref() increments the reference count on the given SSL_SESSION +structure. + +SSL_SESSION_free() decrements the reference count of B<session> and removes +the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated +memory, if the reference count has reached 0. +If B<session> is NULL nothing is done. + +=head1 NOTES + +SSL_SESSION objects are allocated, when a TLS/SSL handshake operation +is successfully completed. Depending on the settings, see +L<SSL_CTX_set_session_cache_mode(3)>, +the SSL_SESSION objects are internally referenced by the SSL_CTX and +linked into its session cache. SSL objects may be using the SSL_SESSION object; +as a session may be reused, several SSL objects may be using one SSL_SESSION +object at the same time. It is therefore crucial to keep the reference +count (usage information) correct and not delete a SSL_SESSION object +that is still used, as this may lead to program failures due to +dangling pointers. These failures may also appear delayed, e.g. +when an SSL_SESSION object was completely freed as the reference count +incorrectly became 0, but it is still referenced in the internal +session cache and the cache list is processed during a +L<SSL_CTX_flush_sessions(3)> operation. + +SSL_SESSION_free() must only be called for SSL_SESSION objects, for +which the reference count was explicitly incremented (e.g. +by calling SSL_get1_session(), see L<SSL_get_session(3)>) +or when the SSL_SESSION object was generated outside a TLS handshake +operation, e.g. by using L<d2i_SSL_SESSION(3)>. +It must not be called on other SSL_SESSION objects, as this would cause +incorrect reference counts and therefore program failures. + +=head1 RETURN VALUES + +SSL_SESSION_new returns a pointer to the newly allocated SSL_SESSION structure +or NULL on error. + +SSL_SESSION_up_ref returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_get_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_flush_sessions(3)>, +L<d2i_SSL_SESSION(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod new file mode 100644 index 0000000..fdd36ed --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_cipher - retrieve the SSL cipher associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const SSL_CIPHER *SSL_SESSION_get0_cipher(const SSL_SESSSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_cipher() retrieves the cipher that was used by the +connection when the session was created, or NULL if it cannot be determined. + +The value returned is a pointer to an object maintained within B<s> and +should not be released. + +=head1 SEE ALSO + +L<ssl(3)>, +L<d2i_SSL_SESSION(3)>, +L<SSL_SESSION_get_time(3)>, +L<SSL_SESSION_get0_hostname(3)>, +L<SSL_SESSION_free(3)> + +=head1 HISTORY + +SSL_SESSION_get0_cipher() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod new file mode 100644 index 0000000..6fb12be --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_hostname - retrieve the SNI hostname associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_SESSION_get0_hostname(const SSL_SESSSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the +client when the session was created, or NULL if no value was sent. + +The value returned is a pointer to memory maintained within B<s> and +should not be free'd. + +=head1 SEE ALSO + +L<ssl(3)>, +L<d2i_SSL_SESSION(3)>, +L<SSL_SESSION_get_time(3)>, +L<SSL_SESSION_free(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod new file mode 100644 index 0000000..ee4a256 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_id_context, +SSL_SESSION_set1_id_context +- get and set the SSL ID context associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s, + unsigned int *len) + int SSL_SESSION_set1_id_context(SSL_SESSION *s, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + +=head1 DESCRIPTION + +See L<SSL_CTX_set_session_id_context(3)> for further details on session ID +contexts. + +SSL_SESSION_get0_id_context() returns the ID context associated with +the SSL/TLS session B<s>. The length of the ID context is written to +B<*len> if B<len> is not NULL. + +The value returned is a pointer to an object maintained within B<s> and +should not be released. + +SSL_SESSION_set1_id_context() takes a copy of the provided ID context given in +B<sid_ctx> and associates it with the session B<s>. The length of the ID context +is given by B<sid_ctx_len> which must not exceed SSL_MAX_SID_CTX_LENGTH bytes. + +=head1 RETURN VALUES + +SSL_SESSION_set1_id_context() returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_set_session_id_context(3)> + +=head1 HISTORY + +SSL_SESSION_get0_id_context() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod new file mode 100644 index 0000000..a95f8a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_peer +- get details about peer's certificate for a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + X509 *SSL_SESSION_get0_peer(SSL_SESSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_peer() returns the peer certificate associated with the session +B<s> or NULL if no peer certificate is available. The caller should not free the +returned value (unless L<X509_up_ref(3)> has also been called). + +=head1 RETURN VALUES + +SSL_SESSION_get0_peer() returns a pointer to the peer certificate or NULL if +no peer certificate is available. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod new file mode 100644 index 0000000..5045c53 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_compress_id +- get details about the compression associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + unsigned int SSL_SESSION_get_compress_id(const SSL_SESSION *s); + +=head1 DESCRIPTION + +If compression has been negotiated for an ssl session then +SSL_SESSION_get_compress_id() will return the id for the compression method or +0 otherwise. The only built-in supported compression method is zlib which has an +id of 1. + +=head1 RETURN VALUES + +SSL_SESSION_get_compress_id() returns the id of the compression method or 0 if +none. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod new file mode 100644 index 0000000..e922abc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_SESSION_set_ex_data, +SSL_SESSION_get_ex_data +- get and set application specific data on a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_set_ex_data(SSL_SESSION *ss, int idx, void *data); + void *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx); + +=head1 DESCRIPTION + +SSL_SESSION_set_ex_data() enables an application to store arbitrary application +specific data B<data> in an SSL_SESSION structure B<ss>. The index B<idx> should +be a value previously returned from a call to L<CRYPTO_get_ex_new_index(3)>. + +SSL_SESSION_get_ex_data() retrieves application specific data previously stored +in an SSL_SESSION structure B<s>. The B<idx> value should be the same as that +used when originally storing the data. + +=head1 RETURN VALUES + +SSL_SESSION_set_ex_data() returns 1 for success or 0 for failure. + +SSL_SESSION_get_ex_data() returns the previously stored value or NULL on +failure. NULL may also be a valid value. + +=head1 SEE ALSO + +L<ssl(3)>, +L<CRYPTO_get_ex_new_index(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod new file mode 100644 index 0000000..a033fdd --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_protocol_version - retrieve session protocol version + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_get_protocol_version(const SSL_SESSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get_protocol_version() returns the protocol version number used +by session B<s>. + +=head1 RETURN VALUES + +SSL_SESSION_get_protocol_version() returns a number indicating the protocol +version used for the session; this number matches the constants I<e.g.> +B<TLS1_VERSION> or B<TLS1_2_VERSION>. + +Note that the SSL_SESSION_get_protocol_version() function +does B<not> perform a null check on the provided session B<s> pointer. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 HISTORY + +SSL_SESSION_get_protocol_version() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod new file mode 100644 index 0000000..e98d128 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, +SSL_SESSION_set_timeout, +SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout +- retrieve and manipulate session time and timeout settings + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_SESSION_get_time(const SSL_SESSION *s); + long SSL_SESSION_set_time(SSL_SESSION *s, long tm); + long SSL_SESSION_get_timeout(const SSL_SESSION *s); + long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm); + + long SSL_get_time(const SSL_SESSION *s); + long SSL_set_time(SSL_SESSION *s, long tm); + long SSL_get_timeout(const SSL_SESSION *s); + long SSL_set_timeout(SSL_SESSION *s, long tm); + +=head1 DESCRIPTION + +SSL_SESSION_get_time() returns the time at which the session B<s> was +established. The time is given in seconds since the Epoch and therefore +compatible to the time delivered by the time() call. + +SSL_SESSION_set_time() replaces the creation time of the session B<s> with +the chosen value B<tm>. + +SSL_SESSION_get_timeout() returns the timeout value set for session B<s> +in seconds. + +SSL_SESSION_set_timeout() sets the timeout value for session B<s> in seconds +to B<tm>. + +The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout() +functions are synonyms for the SSL_SESSION_*() counterparts. + +=head1 NOTES + +Sessions are expired by examining the creation time and the timeout value. +Both are set at creation time of the session to the actual time and the +default timeout value at creation, respectively, as set by +L<SSL_CTX_set_timeout(3)>. +Using these functions it is possible to extend or shorten the lifetime +of the session. + +=head1 RETURN VALUES + +SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently +valid values. + +SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success. + +If any of the function is passed the NULL pointer for the session B<s>, +0 is returned. + +=head1 SEE ALSO + +L<ssl(7)>, +L<SSL_CTX_set_timeout(3)>, +L<SSL_get_default_timeout(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod new file mode 100644 index 0000000..a84440b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_ticket, +SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint +- get details about the ticket associated with a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_has_ticket(const SSL_SESSION *s); + unsigned long SSL_SESSION_get_ticket_lifetime_hint(const SSL_SESSION *s); + void SSL_SESSION_get0_ticket(const SSL_SESSION *s, const unsigned char **tick, + size_t *len); + +=head1 DESCRIPTION + +SSL_SESSION_has_ticket() returns 1 if there is a Session Ticket associated with +this session, and 0 otherwise. + +SSL_SESSION_get_ticket_lifetime_hint returns the lifetime hint in seconds +associated with the session ticket. + +SSL_SESSION_get0_ticket obtains a pointer to the ticket associated with a +session. The length of the ticket is written to B<*len>. If B<tick> is non +NULL then a pointer to the ticket is written to B<*tick>. The pointer is only +valid while the connection is in use. The session (and hence the ticket pointer) +may also become invalid as a result of a call to SSL_CTX_flush_sessions(). + +=head1 SEE ALSO + +L<ssl(7)>, +L<d2i_SSL_SESSION(3)>, +L<SSL_SESSION_get_time(3)>, +L<SSL_SESSION_free(3)> + +=head1 HISTORY + +SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint and +SSL_SESSION_get0_ticket were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod new file mode 100644 index 0000000..9a44c11 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_SESSION_print, +SSL_SESSION_print_fp, +SSL_SESSION_print_keylog +- printf information about a session + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_SESSION_print(BIO *fp, const SSL_SESSION *ses); + int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *ses); + int SSL_SESSION_print_keylog(BIO *bp, const SSL_SESSION *x); + +=head1 DESCRIPTION + +SSL_SESSION_print() prints summary information about the session provided in +B<ses> to the BIO B<fp>. + +SSL_SESSION_print_fp() does the same as SSL_SESSION_print() except it prints it +to the FILE B<fp>. + +SSL_SESSION_print_keylog() prints session information to the provided BIO <bp> +in NSS keylog format. + +=head1 RETURN VALUES + +SSL_SESSION_print(), SSL_SESSION_print_fp() and SSL_SESSION_print_keylog return +1 on success or 0 on error. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod new file mode 100644 index 0000000..0bd9b83 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_id, +SSL_SESSION_set1_id +- get and set the SSL session ID + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const unsigned char *SSL_SESSION_get_id(const SSL_SESSION *s, + unsigned int *len) + int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid, + unsigned int sid_len); + +=head1 DESCRIPTION + +SSL_SESSION_get_id() returns a pointer to the internal session id value for the +session B<s>. The length of the id in bytes is stored in B<*len>. The length may +be 0. The caller should not free the returned pointer directly. + +SSL_SESSION_set1_id() sets the the session ID for the B<ssl> SSL/TLS session +to B<sid> of length B<sid_len>. + +=head1 RETURN VALUES + +SSL_SESSION_get_id() returns a pointer to the session id value. +SSL_SESSION_set1_id() returns 1 for success and 0 for failure, for example +if the supplied session ID length exceeds B<SSL_MAX_SSL_SESSION_ID_LENGTH>. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 HISTORY + +SSL_SESSION_set1_id() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_accept.pod b/openssl-1.1.0h/doc/ssl/SSL_accept.pod new file mode 100644 index 0000000..3248cac --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_accept.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_accept(SSL *ssl); + +=head1 DESCRIPTION + +SSL_accept() waits for a TLS/SSL client to initiate the TLS/SSL handshake. +The communication channel must already have been set and assigned to the +B<ssl> by setting an underlying B<BIO>. + +=head1 NOTES + +The behaviour of SSL_accept() depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_accept() will only return once the +handshake has been finished or an error occurred. + +If the underlying BIO is B<non-blocking>, SSL_accept() will also return +when the underlying BIO could not satisfy the needs of SSL_accept() +to continue the handshake, indicating the problem by the return value -1. +In this case a call to SSL_get_error() with the +return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_accept(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=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 +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_connect(3)>, +L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>, +L<SSL_set_connect_state(3)>, +L<SSL_do_handshake(3)>, +L<SSL_CTX_new(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod b/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod new file mode 100644 index 0000000..6e2768e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod @@ -0,0 +1,242 @@ +=pod + +=head1 NAME + +SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_alert_type_string(int value); + const char *SSL_alert_type_string_long(int value); + + const char *SSL_alert_desc_string(int value); + const char *SSL_alert_desc_string_long(int value); + +=head1 DESCRIPTION + +SSL_alert_type_string() returns a one letter string indicating the +type of the alert specified by B<value>. + +SSL_alert_type_string_long() returns a string indicating the type of the alert +specified by B<value>. + +SSL_alert_desc_string() returns a two letter string as a short form +describing the reason of the alert specified by B<value>. + +SSL_alert_desc_string_long() returns a string describing the reason +of the alert specified by B<value>. + +=head1 NOTES + +When one side of an SSL/TLS communication wants to inform the peer about +a special situation, it sends an alert. The alert is sent as a special message +and does not influence the normal data stream (unless its contents results +in the communication being canceled). + +A warning alert is sent, when a non-fatal error condition occurs. The +"close notify" alert is sent as a warning alert. Other examples for +non-fatal errors are certificate errors ("certificate expired", +"unsupported certificate"), for which a warning alert may be sent. +(The sending party may however decide to send a fatal error.) The +receiving side may cancel the connection on reception of a warning +alert on it discretion. + +Several alert messages must be sent as fatal alert messages as specified +by the TLS RFC. A fatal alert always leads to a connection abort. + +=head1 RETURN VALUES + +The following strings can occur for SSL_alert_type_string() or +SSL_alert_type_string_long(): + +=over 4 + +=item "W"/"warning" + +=item "F"/"fatal" + +=item "U"/"unknown" + +This indicates that no support is available for this alert type. +Probably B<value> does not contain a correct alert message. + +=back + +The following strings can occur for SSL_alert_desc_string() or +SSL_alert_desc_string_long(): + +=over 4 + +=item "CN"/"close notify" + +The connection shall be closed. This is a warning alert. + +=item "UM"/"unexpected message" + +An inappropriate message was received. This alert is always fatal +and should never be observed in communication between proper +implementations. + +=item "BM"/"bad record mac" + +This alert is returned if a record is received with an incorrect +MAC. This message is always fatal. + +=item "DF"/"decompression failure" + +The decompression function received improper input (e.g. data +that would expand to excessive length). This message is always +fatal. + +=item "HF"/"handshake failure" + +Reception of a handshake_failure alert message indicates that the +sender was unable to negotiate an acceptable set of security +parameters given the options available. This is a fatal error. + +=item "NC"/"no certificate" + +A client, that was asked to send a certificate, does not send a certificate +(SSLv3 only). + +=item "BC"/"bad certificate" + +A certificate was corrupt, contained signatures that did not +verify correctly, etc + +=item "UC"/"unsupported certificate" + +A certificate was of an unsupported type. + +=item "CR"/"certificate revoked" + +A certificate was revoked by its signer. + +=item "CE"/"certificate expired" + +A certificate has expired or is not currently valid. + +=item "CU"/"certificate unknown" + +Some other (unspecified) issue arose in processing the +certificate, rendering it unacceptable. + +=item "IP"/"illegal parameter" + +A field in the handshake was out of range or inconsistent with +other fields. This is always fatal. + +=item "DC"/"decryption failed" + +A TLSCiphertext decrypted in an invalid way: either it wasn't an +even multiple of the block length or its padding values, when +checked, weren't correct. This message is always fatal. + +=item "RO"/"record overflow" + +A TLSCiphertext record was received which had a length more than +2^14+2048 bytes, or a record decrypted to a TLSCompressed record +with more than 2^14+1024 bytes. This message is always fatal. + +=item "CA"/"unknown CA" + +A valid certificate chain or partial chain was received, but the +certificate was not accepted because the CA certificate could not +be located or couldn't be matched with a known, trusted CA. This +message is always fatal. + +=item "AD"/"access denied" + +A valid certificate was received, but when access control was +applied, the sender decided not to proceed with negotiation. +This message is always fatal. + +=item "DE"/"decode error" + +A message could not be decoded because some field was out of the +specified range or the length of the message was incorrect. This +message is always fatal. + +=item "CY"/"decrypt error" + +A handshake cryptographic operation failed, including being +unable to correctly verify a signature, decrypt a key exchange, +or validate a finished message. + +=item "ER"/"export restriction" + +A negotiation not in compliance with export restrictions was +detected; for example, attempting to transfer a 1024 bit +ephemeral RSA key for the RSA_EXPORT handshake method. This +message is always fatal. + +=item "PV"/"protocol version" + +The protocol version the client has attempted to negotiate is +recognized, but not supported. (For example, old protocol +versions might be avoided for security reasons). This message is +always fatal. + +=item "IS"/"insufficient security" + +Returned instead of handshake_failure when a negotiation has +failed specifically because the server requires ciphers more +secure than those supported by the client. This message is always +fatal. + +=item "IE"/"internal error" + +An internal error unrelated to the peer or the correctness of the +protocol makes it impossible to continue (such as a memory +allocation failure). This message is always fatal. + +=item "US"/"user canceled" + +This handshake is being canceled for some reason unrelated to a +protocol failure. If the user cancels an operation after the +handshake is complete, just closing the connection by sending a +close_notify is more appropriate. This alert should be followed +by a close_notify. This message is generally a warning. + +=item "NR"/"no renegotiation" + +Sent by the client in response to a hello request or by the +server in response to a client hello after initial handshaking. +Either of these would normally lead to renegotiation; when that +is not appropriate, the recipient should respond with this alert; +at that point, the original requester can decide whether to +proceed with the connection. One case where this would be +appropriate would be where a server has spawned a process to +satisfy a request; the process might receive security parameters +(key length, authentication, etc.) at startup and it might be +difficult to communicate changes to these parameters after that +point. This message is always a warning. + +=item "UP"/"unknown PSK identity" + +Sent by the server to indicate that it does not recognize a PSK +identity or an SRP identity. + +=item "UK"/"unknown" + +This indicates that no description is available for this alert type. +Probably B<value> does not contain a correct alert message. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_CTX_set_info_callback(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod b/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod new file mode 100644 index 0000000..8691994 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod @@ -0,0 +1,94 @@ +=pod + +=head1 NAME + +SSL_check_chain - check certificate chain suitability + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain); + +=head1 DESCRIPTION + +SSL_check_chain() checks whether certificate B<x>, private key B<pk> and +certificate chain B<chain> is suitable for use with the current session +B<s>. + +=head1 RETURN VALUES + +SSL_check_chain() returns a bitmap of flags indicating the validity of the +chain. + +B<CERT_PKEY_VALID>: the chain can be used with the current session. +If this flag is B<not> set then the certificate will never be used even +if the application tries to set it because it is inconsistent with the +peer preferences. + +B<CERT_PKEY_SIGN>: the EE key can be used for signing. + +B<CERT_PKEY_EE_SIGNATURE>: the signature algorithm of the EE certificate is +acceptable. + +B<CERT_PKEY_CA_SIGNATURE>: the signature algorithms of all CA certificates +are acceptable. + +B<CERT_PKEY_EE_PARAM>: the parameters of the end entity certificate are +acceptable (e.g. it is a supported curve). + +B<CERT_PKEY_CA_PARAM>: the parameters of all CA certificates are acceptable. + +B<CERT_PKEY_EXPLICIT_SIGN>: the end entity certificate algorithm +can be used explicitly for signing (i.e. it is mentioned in the signature +algorithms extension). + +B<CERT_PKEY_ISSUER_NAME>: the issuer name is acceptable. This is only +meaningful for client authentication. + +B<CERT_PKEY_CERT_TYPE>: the certificate type is acceptable. Only meaningful +for client authentication. + +B<CERT_PKEY_SUITEB>: chain is suitable for Suite B use. + +=head1 NOTES + +SSL_check_chain() must be called in servers after a client hello message or in +clients after a certificate request message. It will typically be called +in the certificate callback. + +An application wishing to support multiple certificate chains may call this +function on each chain in turn: starting with the one it considers the +most secure. It could then use the chain of the first set which returns +suitable flags. + +As a minimum the flag B<CERT_PKEY_VALID> must be set for a chain to be +usable. An application supporting multiple chains with different CA signature +algorithms may also wish to check B<CERT_PKEY_CA_SIGNATURE> too. If no +chain is suitable a server should fall back to the most secure chain which +sets B<CERT_PKEY_VALID>. + +The validity of a chain is determined by checking if it matches a supported +signature algorithm, supported curves and in the case of client authentication +certificate types and issuer names. + +Since the supported signature algorithms extension is only used in TLS 1.2 +and DTLS 1.2 the results for earlier versions of TLS and DTLS may not be +very useful. Applications may wish to specify a different "legacy" chain +for earlier versions of TLS or DTLS. + +=head1 SEE ALSO + +L<SSL_CTX_set_cert_cb(3)>, +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_clear.pod b/openssl-1.1.0h/doc/ssl/SSL_clear.pod new file mode 100644 index 0000000..ed0ad60 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_clear.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +SSL_clear - reset SSL object to allow another connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_clear(SSL *ssl); + +=head1 DESCRIPTION + +Reset B<ssl> to allow another connection. All settings (method, ciphers, +BIOs) are kept. + +=head1 NOTES + +SSL_clear is used to prepare an SSL object for a new connection. While all +settings are kept, a side effect is the handling of the current SSL session. +If a session is still B<open>, it is considered bad and will be removed +from the session cache, as required by RFC2246. A session is considered open, +if L<SSL_shutdown(3)> was not called for the connection +or at least L<SSL_set_shutdown(3)> was used to +set the SSL_SENT_SHUTDOWN state. + +If a session was closed cleanly, the session object will be kept and all +settings corresponding. This explicitly means, that e.g. the special method +used during the session will be kept for the next handshake. So if the +session was a TLSv1 session, a SSL client object will use a TLSv1 client +method for the next handshake and a SSL server object will use a TLSv1 +server method, even if TLS_*_methods were chosen on startup. This +will might lead to connection failures (see L<SSL_new(3)>) +for a description of the method's properties. + +=head1 WARNINGS + +SSL_clear() resets the SSL object to allow for another connection. The +reset operation however keeps several settings of the last sessions +(some of these settings were made automatically during the last +handshake). It only makes sense for a new connection with the exact +same peer that shares these settings, and may fail if that peer +changes its settings between connections. Use the sequence +L<SSL_get_session(3)>; +L<SSL_new(3)>; +L<SSL_set_session(3)>; +L<SSL_free(3)> +instead to avoid such failures +(or simply L<SSL_free(3)>; L<SSL_new(3)> +if session reuse is not desired). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item Z<>0 + +The SSL_clear() operation could not be performed. Check the error stack to +find out the reason. + +=item Z<>1 + +The SSL_clear() operation was successful. + +=back + +L<SSL_new(3)>, L<SSL_free(3)>, +L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>, +L<SSL_CTX_set_options(3)>, L<ssl(3)>, +L<SSL_CTX_set_client_cert_cb(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_connect.pod b/openssl-1.1.0h/doc/ssl/SSL_connect.pod new file mode 100644 index 0000000..df198f9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_connect.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_connect(SSL *ssl); + +=head1 DESCRIPTION + +SSL_connect() initiates the TLS/SSL handshake with a server. The communication +channel must already have been set and assigned to the B<ssl> by setting an +underlying B<BIO>. + +=head1 NOTES + +The behaviour of SSL_connect() depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_connect() will only return once the +handshake has been finished or an error occurred. + +If the underlying BIO is B<non-blocking>, SSL_connect() will also return +when the underlying BIO could not satisfy the needs of SSL_connect() +to continue the handshake, indicating the problem by the return value -1. +In this case a call to SSL_get_error() with the +return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_connect(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=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 +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_accept(3)>, +L<SSL_shutdown(3)>, L<ssl(3)>, L<bio(3)>, +L<SSL_set_connect_state(3)>, +L<SSL_do_handshake(3)>, +L<SSL_CTX_new(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod b/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod new file mode 100644 index 0000000..ffb71cc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +SSL_do_handshake - perform a TLS/SSL handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_do_handshake(SSL *ssl); + +=head1 DESCRIPTION + +SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the +connection is in client mode, the handshake will be started. The handshake +routines may have to be explicitly set in advance using either +L<SSL_set_connect_state(3)> or +L<SSL_set_accept_state(3)>. + +=head1 NOTES + +The behaviour of SSL_do_handshake() depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_do_handshake() will only return +once the handshake has been finished or an error occurred. + +If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return +when the underlying BIO could not satisfy the needs of SSL_do_handshake() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_do_handshake(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=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 +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_connect(3)>, +L<SSL_accept(3)>, L<ssl(3)>, L<bio(3)>, +L<SSL_set_connect_state(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod b/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod new file mode 100644 index 0000000..ccb99ec --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_export_keying_material - obtain keying material for application use + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen, + const char *label, size_t llen, + const unsigned char *context, + size_t contextlen, int use_context); + +=head1 DESCRIPTION + +During the creation of a TLS or DTLS connection shared keying material is +established between the two endpoints. The function SSL_export_keying_material() +enables an application to use some of this keying material for its own purposes +in accordance with RFC5705. + +An application may need to securely establish the context within which this +keying material will be used. For example this may include identifiers for the +application session, application algorithms or parameters, or the lifetime of +the context. The context value is left to the application but must be the same +on both sides of the communication. + +For a given SSL connection B<s>, B<olen> bytes of data will be written to +B<out>. The application specific context should be supplied in the location +pointed to by B<context> and should be B<contextlen> bytes long. Provision of +a context is optional. If the context should be omitted entirely then +B<use_context> should be set to 0. Otherwise it should be any other value. If +B<use_context> is 0 then the values of B<context> and B<contextlen> are ignored. +Note that a zero length context is treated differently to no context at all, and +will result in different keying material being returned. + +An application specific label should be provided in the location pointed to by +B<label> and should be B<llen> bytes long. Typically this will be a value from +the IANA Exporter Label Registry +(L<https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels>). +Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard +to be used without registration. + +Note that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and +above. Attempting to use it in SSLv3 will result in an error. + +=head1 RETURN VALUES + +SSL_export_keying_material() returns 0 or -1 on failure or 1 on success. + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_extension_supported.pod b/openssl-1.1.0h/doc/ssl/SSL_extension_supported.pod new file mode 100644 index 0000000..166c35a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_extension_supported.pod @@ -0,0 +1,145 @@ +=pod + +=head1 NAME + +SSL_extension_supported, +SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext, +custom_ext_add_cb, custom_ext_free_cb, custom_ext_parse_cb +- custom TLS extension handling + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type, + custom_ext_add_cb add_cb, + custom_ext_free_cb free_cb, void *add_arg, + custom_ext_parse_cb parse_cb, + void *parse_arg); + + int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type, + custom_ext_add_cb add_cb, + custom_ext_free_cb free_cb, void *add_arg, + custom_ext_parse_cb parse_cb, + void *parse_arg); + + int SSL_extension_supported(unsigned int ext_type); + + typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type, + const unsigned char **out, + size_t *outlen, int *al, + void *add_arg); + + typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type, + const unsigned char *out, + void *add_arg); + + typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type, + const unsigned char *in, + size_t inlen, int *al, + void *parse_arg); + + +=head1 DESCRIPTION + +SSL_CTX_add_client_custom_ext() adds a custom extension for a TLS client +with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and +B<parse_cb>. + +SSL_CTX_add_server_custom_ext() adds a custom extension for a TLS server +with extension type B<ext_type> and callbacks B<add_cb>, B<free_cb> and +B<parse_cb>. + +In both cases the extension type must not be handled by OpenSSL internally +or an error occurs. + +SSL_extension_supported() returns 1 if the extension B<ext_type> is handled +internally by OpenSSL and 0 otherwise. + +=head1 EXTENSION CALLBACKS + +The callback B<add_cb> is called to send custom extension data to be +included in ClientHello for TLS clients or ServerHello for servers. The +B<ext_type> parameter is set to the extension type which will be added and +B<add_arg> to the value set when the extension handler was added. + +If the application wishes to include the extension B<ext_type> it should +set B<*out> to the extension data, set B<*outlen> to the length of the +extension data and return 1. + +If the B<add_cb> does not wish to include the extension it must return 0. + +If B<add_cb> returns -1 a fatal handshake error occurs using the TLS +alert value specified in B<*al>. + +For clients (but not servers) if B<add_cb> is set to NULL a zero length +extension is added for B<ext_type>. + +For clients every registered B<add_cb> is always called to see if the +application wishes to add an extension to ClientHello. + +For servers every registered B<add_cb> is called once if and only if the +corresponding extension was received in ClientHello to see if the application +wishes to add the extension to ServerHello. That is, if no corresponding extension +was received in ClientHello then B<add_cb> will not be called. + +If an extension is added (that is B<add_cb> returns 1) B<free_cb> is called +(if it is set) with the value of B<out> set by the add callback. It can be +used to free up any dynamic extension data set by B<add_cb>. Since B<out> is +constant (to permit use of constant data in B<add_cb>) applications may need to +cast away const to free the data. + +The callback B<parse_cb> receives data for TLS extensions. For TLS clients +the extension data will come from ServerHello and for TLS servers it will +come from ClientHello. + +The extension data consists of B<inlen> bytes in the buffer B<in> for the +extension B<extension_type>. + +If the B<parse_cb> considers the extension data acceptable it must return +1. If it returns 0 or a negative value a fatal handshake error occurs +using the TLS alert value specified in B<*al>. + +The buffer B<in> is a temporary internal buffer which will not be valid after +the callback returns. + +=head1 NOTES + +The B<add_arg> and B<parse_arg> parameters can be set to arbitrary values +which will be passed to the corresponding callbacks. They can, for example, +be used to store the extension data received in a convenient structure or +pass the extension data to be added or freed when adding extensions. + +The B<ext_type> parameter corresponds to the B<extension_type> field of +RFC5246 et al. It is B<not> a NID. + +If the same custom extension type is received multiple times a fatal +B<decode_error> alert is sent and the handshake aborts. If a custom extension +is received in ServerHello which was not sent in ClientHello a fatal +B<unsupported_extension> alert is sent and the handshake is aborted. The +ServerHello B<add_cb> callback is only called if the corresponding extension +was received in ClientHello. This is compliant with the TLS specifications. +This behaviour ensures that each callback is called at most once and that +an application can never send unsolicited extensions. + +=head1 RETURN VALUES + +SSL_CTX_add_client_custom_ext() and SSL_CTX_add_server_custom_ext() return 1 for +success and 0 for failure. A failure can occur if an attempt is made to +add the same B<ext_type> more than once, if an attempt is made to use an +extension type handled internally by OpenSSL or if an internal error occurs +(for example a memory allocation failure). + +SSL_extension_supported() returns 1 if the extension B<ext_type> is handled +internally by OpenSSL and 0 otherwise. + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_free.pod b/openssl-1.1.0h/doc/ssl/SSL_free.pod new file mode 100644 index 0000000..eb69a16 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_free.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +SSL_free - free an allocated SSL structure + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_free(SSL *ssl); + +=head1 DESCRIPTION + +SSL_free() decrements the reference count of B<ssl>, and removes the SSL +structure pointed to by B<ssl> and frees up the allocated memory if the +reference count has reached 0. +If B<ssl> is NULL nothing is done. + +=head1 NOTES + +SSL_free() also calls the free()ing procedures for indirectly affected items, if +applicable: the buffering BIO, the read and write BIOs, +cipher lists specially created for this B<ssl>, the B<SSL_SESSION>. +Do not explicitly free these indirectly freed up items before or after +calling SSL_free(), as trying to free things twice may lead to program +failure. + +The ssl session has reference counts from two users: the SSL object, for +which the reference count is removed by SSL_free() and the internal +session cache. If the session is considered bad, because +L<SSL_shutdown(3)> was not called for the connection +and L<SSL_set_shutdown(3)> was not used to set the +SSL_SENT_SHUTDOWN state, the session will also be removed +from the session cache as required by RFC2246. + +=head1 RETURN VALUES + +SSL_free() does not provide diagnostic information. + +L<SSL_new(3)>, L<SSL_clear(3)>, +L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>, +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get0_peer_scts.pod b/openssl-1.1.0h/doc/ssl/SSL_get0_peer_scts.pod new file mode 100644 index 0000000..05d39fe --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get0_peer_scts.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +SSL_get0_peer_scts - get SCTs received + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const STACK_OF(SCT) *SSL_get0_peer_scts(SSL *s); + +=head1 DESCRIPTION + +SSL_get0_peer_scts() returns the signed certificate timestamps (SCTs) that have +been received. If this is the first time that this function has been called for +a given B<SSL> instance, it will examine the TLS extensions, OCSP response and +the peer's certificate for SCTs. Future calls will return the same SCTs. + +=head1 RESTRICTIONS + +If no Certificate Transparency validation callback has been set (using +B<SSL_CTX_set_ct_validation_callback> or B<SSL_set_ct_validation_callback>), +this function is not guaranteed to return all of the SCTs that the peer is +capable of sending. + +=head1 RETURN VALUES + +SSL_get0_peer_scts() returns a list of SCTs found, or NULL if an error occurs. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_ct_validation_callback(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_SSL_CTX.pod b/openssl-1.1.0h/doc/ssl/SSL_get_SSL_CTX.pod new file mode 100644 index 0000000..98b9bc6 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_SSL_CTX.pod @@ -0,0 +1,35 @@ +=pod + +=head1 NAME + +SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_SSL_CTX() returns a pointer to the SSL_CTX object, from which +B<ssl> was created with L<SSL_new(3)>. + +=head1 RETURN VALUES + +The pointer to the SSL_CTX object is returned. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_new(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_all_async_fds.pod b/openssl-1.1.0h/doc/ssl/SSL_get_all_async_fds.pod new file mode 100644 index 0000000..b4fa4ee --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_all_async_fds.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +SSL_waiting_for_async, +SSL_get_all_async_fds, +SSL_get_changed_async_fds +- manage asynchronous operations + +=for comment multiple includes + +=head1 SYNOPSIS + + #include <openssl/async.h> + #include <openssl/ssl.h> + + int SSL_waiting_for_async(SSL *s); + int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds); + int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds, + OSSL_ASYNC_FD *delfd, size_t *numdelfds); + +=head1 DESCRIPTION + +SSL_waiting_for_async() determines whether an SSL connection is currently +waiting for asynchronous operations to complete (see the SSL_MODE_ASYNC mode in +L<SSL_CTX_set_mode(3)>). + +SSL_get_all_async_fds() returns a list of file descriptor which can be used in a +call to select() or poll() to determine whether the current asynchronous +operation has completed or not. A completed operation will result in data +appearing as "read ready" on the file descriptor (no actual data should be read +from the file descriptor). This function should only be called if the SSL object +is currently waiting for asynchronous work to complete (i.e. +SSL_ERROR_WANT_ASYNC has been received - see L<SSL_get_error(3)>). Typically the +list will only contain one file descriptor. However if multiple asynchronous +capable engines are in use then more than one is possible. The number of file +descriptors returned is stored in B<*numfds> and the file descriptors themselves +are in B<*fds>. The B<fds> parameter may be NULL in which case no file +descriptors are returned but B<*numfds> is still populated. It is the callers +responsibility to ensure sufficient memory is allocated at B<*fds> so typically +this function is called twice (once with a NULL B<fds> parameter and once +without). + +SSL_get_changed_async_fds() returns a list of the asynchronous file descriptors +that have been added and a list that have been deleted since the last +SSL_ERROR_WANT_ASYNC was received (or since the SSL object was created if no +SSL_ERROR_WANT_ASYNC has been received). Similar to SSL_get_all_async_fds() it +is the callers responsibility to ensure that B<*addfd> and B<*delfd> have +sufficient memory allocated, although they may be NULL. The number of added fds +and the number of deleted fds are stored in B<*numaddfds> and B<*numdelfds> +respectively. + +=head1 RETURN VALUES + +SSL_waiting_for_async() will return 1 if the current SSL operation is waiting +for an async operation to complete and 0 otherwise. + +SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or +0 on error. + +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)> + +=head1 HISTORY + +SSL_waiting_for_async(), SSL_get_all_async_fds() and SSL_get_changed_async_fds() +were first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_ciphers.pod b/openssl-1.1.0h/doc/ssl/SSL_get_ciphers.pod new file mode 100644 index 0000000..cc55095 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_ciphers.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +SSL_get1_supported_ciphers, SSL_get_client_ciphers, +SSL_get_ciphers, SSL_CTX_get_ciphers, SSL_get_cipher_list +- get list of available SSL_CIPHERs + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl); + STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx); + STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s); + STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl); + const char *SSL_get_cipher_list(const SSL *ssl, int priority); + +=head1 DESCRIPTION + +SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>, +sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL +is returned. + +SSL_CTX_get_ciphers() returns the stack of available SSL_CIPHERs for B<ctx>. + +SSL_get1_supported_ciphers() returns the stack of enabled SSL_CIPHERs for +B<ssl>, sorted by preference. +The list depends on settings like the cipher list, the supported protocol +versions, the security level, and the enabled signature algorithms. +SRP and PSK ciphers are only enabled if the appropriate callbacks or settings +have been applied. +This is the list that will be sent by the client to the server. +The list supported by the server might include more ciphers in case there is a +hole in the list of supported protocols. +The server will also not use ciphers from this list depending on the +configured certificates and DH parameters. +If B<ssl> is NULL or no ciphers are available, NULL is returned. + +SSL_get_client_ciphers() returns the stack of available SSL_CIPHERs matching the +list received from the client on B<ssl>. If B<ssl> is NULL, no ciphers are +available, or B<ssl> is not operating in server mode, NULL is returned. + +SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER +listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are +available, or there are less ciphers than B<priority> available, NULL +is returned. + +=head1 NOTES + +The details of the ciphers obtained by SSL_get_ciphers(), SSL_CTX_get_ciphers() +SSL_get1_supported_ciphers() and SSL_get_client_ciphers() can be obtained using +the L<SSL_CIPHER_get_name(3)> family of functions. + +Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the +sorted list of available ciphers, until NULL is returned. + +Note: SSL_get_ciphers(), SSL_CTX_get_ciphers() and SSL_get_client_ciphers() +return a pointer to an internal cipher stack, which will be freed later on when +the SSL or SSL_SESSION object is freed. Therefore, the calling code B<MUST NOT> +free the return value itself. + +The stack returned by SSL_get1_supported_ciphers() should be freed using +sk_SSL_CIPHER_free(). + +=head1 RETURN VALUES + +See DESCRIPTION + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>, +L<SSL_CIPHER_get_name(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_client_CA_list.pod b/openssl-1.1.0h/doc/ssl/SSL_get_client_CA_list.pod new file mode 100644 index 0000000..b6092fe --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_client_CA_list.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); + STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for +B<ctx> using L<SSL_CTX_set_client_CA_list(3)>. + +SSL_get_client_CA_list() returns the list of client CAs explicitly +set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with +L<SSL_CTX_set_client_CA_list(3)>, when in +server mode. In client mode, SSL_get_client_CA_list returns the list of +client CAs sent from the server, if any. + +=head1 RETURN VALUES + +SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return +diagnostic information. + +SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return +values: + +=over 4 + +=item STACK_OF(X509_NAMES) + +List of CA names explicitly set (for B<ctx> or in server mode) or send +by the server (client mode). + +=item NULL + +No client CA list was explicitly set (for B<ctx> or in server mode) or +the server did not send a list of CAs (client mode). + +=back + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)>, +L<SSL_CTX_set_client_cert_cb(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_client_random.pod b/openssl-1.1.0h/doc/ssl/SSL_get_client_random.pod new file mode 100644 index 0000000..46a2aa3 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_client_random.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +SSL_get_client_random, SSL_get_server_random, SSL_SESSION_get_master_key - retrieve internal TLS/SSL random values and master key + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen); + size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen); + size_t SSL_SESSION_get_master_key(const SSL_SESSION *session, unsigned char *out, size_t outlen); + +=head1 DESCRIPTION + +SSL_get_client_random() extracts the random value sent from the client +to the server during the initial SSL/TLS handshake. It copies as many +bytes as it can of this value into the buffer provided in B<out>, +which must have at least B<outlen> bytes available. It returns the +total number of bytes that were actually copied. If B<outlen> is +zero, SSL_get_client_random() copies nothing, and returns the +total size of the client_random value. + +SSL_get_server_random() behaves the same, but extracts the random value +sent from the server to the client during the initial SSL/TLS handshake. + +SSL_SESSION_get_master_key() behaves the same, but extracts the master +secret used to guarantee the security of the SSL/TLS session. This one +can be dangerous if misused; see NOTES below. + + +=head1 NOTES + +You probably shouldn't use these functions. + +These functions expose internal values from the TLS handshake, for +use in low-level protocols. You probably should not use them, unless +you are implementing something that needs access to the internal protocol +details. + +Despite the names of SSL_get_client_random() and SSL_get_server_random(), they +ARE NOT random number generators. Instead, they return the mostly-random values that +were already generated and used in the TLS protocol. Using them +in place of RAND_bytes() would be grossly foolish. + +The security of your TLS session depends on keeping the master key secret: +do not expose it, or any information about it, to anybody. +If you need to calculate another secret value that depends on the master +secret, you should probably use SSL_export_keying_material() instead, and +forget that you ever saw these functions. + +In current versions of the TLS protocols, the length of client_random +(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for +other outlen arguments to the SSL_get_*_random() functions is provided +in case of the unlikely event that a future version or variant of TLS +uses some other length there. + +Finally, though the "client_random" and "server_random" values are called +"random", many TLS implementations will generate four bytes of those +values based on their view of the current time. + + +=head1 RETURN VALUES + +If B<outlen> is greater than 0, these functions return the number of bytes +actually copied, which will be less than or equal to B<outlen>. + +If B<outlen> is 0, these functions return the maximum number +of bytes they would copy--that is, the length of the underlying field. + +=head1 SEE ALSO + +L<ssl(3)>, +L<RAND_bytes(3)>, +L<SSL_export_keying_material(3)> + + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_current_cipher.pod b/openssl-1.1.0h/doc/ssl/SSL_get_current_cipher.pod new file mode 100644 index 0000000..87cecb0 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_current_cipher.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME + +SSL_get_current_cipher, SSL_get_cipher_name, SSL_get_cipher, +SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl); + + const char *SSL_get_cipher_name(const SSL *s); + const char *SSL_get_cipher(const SSL *s); + int SSL_get_cipher_bits(const SSL *s, int *np) \ + const char *SSL_get_cipher_version(const SSL *s); + +=head1 DESCRIPTION + +SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing +the description of the actually used cipher of a connection established with +the B<ssl> object. +See L<SSL_CIPHER_get_name(3)> for more details. + +SSL_get_cipher_name() obtains the +name of the currently used cipher. +SSL_get_cipher() is identical to SSL_get_cipher_name(). +SSL_get_cipher_bits() is a +macro to obtain the number of secret/algorithm bits used and +SSL_get_cipher_version() returns the protocol name. + +=head1 RETURN VALUES + +SSL_get_current_cipher() returns the cipher actually used, or NULL if +no session has been established. + +=head1 NOTES + +These are implemented as macros. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_CIPHER_get_name(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_default_timeout.pod b/openssl-1.1.0h/doc/ssl/SSL_get_default_timeout.pod new file mode 100644 index 0000000..875d38a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_default_timeout.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_get_default_timeout - get default session timeout value + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_get_default_timeout(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_default_timeout() returns the default timeout value assigned to +SSL_SESSION objects negotiated for the protocol valid for B<ssl>. + +=head1 NOTES + +Whenever a new session is negotiated, it is assigned a timeout value, +after which it will not be accepted for session reuse. If the timeout +value was not explicitly set using +L<SSL_CTX_set_timeout(3)>, the hardcoded default +timeout for the protocol will be used. + +SSL_get_default_timeout() return this hardcoded value, which is 300 seconds +for all currently supported protocols. + +=head1 RETURN VALUES + +See description. + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_session_cache_mode(3)>, +L<SSL_SESSION_get_time(3)>, +L<SSL_CTX_flush_sessions(3)>, +L<SSL_get_default_timeout(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_error.pod b/openssl-1.1.0h/doc/ssl/SSL_get_error.pod new file mode 100644 index 0000000..47d2358 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_error.pod @@ -0,0 +1,143 @@ +=pod + +=head1 NAME + +SSL_get_error - obtain result code for TLS/SSL I/O operation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_error(const SSL *ssl, int ret); + +=head1 DESCRIPTION + +SSL_get_error() returns a result code (suitable for the C "switch" +statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(), +SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by +that TLS/SSL I/O function must be passed to SSL_get_error() in parameter +B<ret>. + +In addition to B<ssl> and B<ret>, SSL_get_error() inspects the +current thread's OpenSSL error queue. Thus, SSL_get_error() must be +used in the same thread that performed the TLS/SSL I/O operation, and no +other OpenSSL function calls should appear in between. The current +thread's error queue must be empty before the TLS/SSL I/O operation is +attempted, or SSL_get_error() will not work reliably. + +=head1 RETURN VALUES + +The following return values can currently occur: + +=over 4 + +=item SSL_ERROR_NONE + +The TLS/SSL I/O operation completed. This result code is returned +if and only if B<ret E<gt> 0>. + +=item SSL_ERROR_ZERO_RETURN + +The TLS/SSL connection has been closed. +If the protocol version is SSL 3.0 or higher, this result code is returned only +if a closure alert has occurred in the protocol, i.e. if the connection has been +closed cleanly. +Note that in this case B<SSL_ERROR_ZERO_RETURN> does not necessarily +indicate that the underlying transport has been closed. + + +=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE + +The operation did not complete; the same TLS/SSL I/O function should be +called again later. If, by then, the underlying B<BIO> has data +available for reading (if the result code is B<SSL_ERROR_WANT_READ>) +or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL +protocol progress will take place, i.e. at least part of an TLS/SSL +record will be read or written. Note that the retry may again lead to +a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition. +There is no fixed upper limit for the number of iterations that +may be necessary until progress becomes visible at application +protocol level. + +For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or +poll() on the underlying socket can be used to find out when the +TLS/SSL I/O function should be retried. + +Caveat: Any TLS/SSL I/O function can lead to either of +B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular, +SSL_read() or SSL_peek() may want to write data and SSL_write() may want +to read data. This is mainly because TLS/SSL handshakes may occur at any +time during the protocol (initiated by either the client or the server); +SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes. + +=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT + +The operation did not complete; the same TLS/SSL I/O function should be +called again later. The underlying BIO was not connected yet to the peer +and the call would block in connect()/accept(). The SSL function should be +called again when the connection is established. These messages can only +appear with a BIO_s_connect() or BIO_s_accept() BIO, respectively. +In order to find out, when the connection has been successfully established, +on many platforms select() or poll() for writing on the socket file descriptor +can be used. + +=item SSL_ERROR_WANT_X509_LOOKUP + +The operation did not complete because an application callback set by +SSL_CTX_set_client_cert_cb() has asked to be called again. +The TLS/SSL I/O function should be called again later. +Details depend on the application. + +=item SSL_ERROR_WANT_ASYNC + +The operation did not complete because an asynchronous engine is still +processing data. This will only occur if the mode has been set to SSL_MODE_ASYNC +using L<SSL_CTX_set_mode(3)> or L<SSL_set_mode(3)> and an asynchronous capable +engine is being used. An application can determine whether the engine has +completed its processing using select() or poll() on the asynchronous wait file +descriptor. This file descriptor is available by calling +L<SSL_get_all_async_fds(3)> or L<SSL_get_changed_async_fds(3)>. The TLS/SSL I/O +function should be called again later. The function B<must> be called from the +same thread that the original call was made from. + +=item SSL_ERROR_WANT_ASYNC_JOB + +The asynchronous job could not be started because there were no async jobs +available in the pool (see ASYNC_init_thread(3)). This will only occur if the +mode has been set to SSL_MODE_ASYNC using L<SSL_CTX_set_mode(3)> or +L<SSL_set_mode(3)> and a maximum limit has been set on the async job pool +through a call to L<ASYNC_init_thread(3)>. The application should retry the +operation after a currently executing asynchronous operation for the current +thread has completed. + +=item SSL_ERROR_SYSCALL + +Some non-recoverable I/O error occurred. +The OpenSSL error queue may contain more information on the error. +For socket I/O on Unix systems, consult B<errno> for details. + +=item SSL_ERROR_SSL + +A failure in the SSL library occurred, usually a protocol error. The +OpenSSL error queue contains more information on the error. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, L<err(3)> + +=head1 HISTORY + +SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_extms_support.pod b/openssl-1.1.0h/doc/ssl/SSL_get_extms_support.pod new file mode 100644 index 0000000..ba4de3a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_extms_support.pod @@ -0,0 +1,40 @@ +=pod + +=head1 NAME + +SSL_get_extms_support - extended master secret support + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_extms_support(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_extms_support() indicates whether the current session used extended +master secret. + +This function is implemented as a macro. + +=head1 RETURN VALUES + +SSL_get_extms_support() returns 1 if the current session used extended +master secret, 0 if it did not and -1 if a handshake is currently in +progress i.e. it is not possible to determine if extended master secret +was used. + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_fd.pod b/openssl-1.1.0h/doc/ssl/SSL_get_fd.pod new file mode 100644 index 0000000..cd5b6ec --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_fd.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_get_fd, SSL_get_rfd, SSL_get_wfd - get file descriptor linked to an SSL object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_fd(const SSL *ssl); + int SSL_get_rfd(const SSL *ssl); + int SSL_get_wfd(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_fd() returns the file descriptor which is linked to B<ssl>. +SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the +read or the write channel, which can be different. If the read and the +write channel are different, SSL_get_fd() will return the file descriptor +of the read channel. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item -1 + +The operation failed, because the underlying BIO is not of the correct type +(suitable for file descriptors). + +=item E<gt>=0 + +The file descriptor linked to B<ssl>. + +=back + +=head1 SEE ALSO + +L<SSL_set_fd(3)>, L<ssl(3)> , L<bio(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_peer_cert_chain.pod b/openssl-1.1.0h/doc/ssl/SSL_get_peer_cert_chain.pod new file mode 100644 index 0000000..f122124 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_peer_cert_chain.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +SSL_get_peer_cert_chain, SSL_get0_verified_chain - get the X509 certificate +chain of the peer + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl); + STACK_OF(X509) *SSL_get0_verified_chain(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_peer_cert_chain() returns a pointer to STACK_OF(X509) certificates +forming the certificate chain sent by 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 +L<SSL_get_peer_certificate(3)>. +If the peer did not present a certificate, NULL is returned. + +NB: SSL_get_peer_cert_chain() returns the peer chain as sent by the peer: it +only consists of certificates the peer has sent (in the order the peer +has sent them) it is B<not> a verified chain. + +SSL_get0_verified_chain() returns the B<verified> certificate chain +of the peer including the peer's end entity certificate. It must be called +after a session has been successfully established. If peer verification was +not successful (as indicated by SSL_get_verify_result() not returning +X509_V_OK) the chain may be incomplete or invalid. + +=head1 NOTES + +If the session is resumed peers do not send certificates so a NULL pointer +is returned by these functions. Applications can call SSL_session_reused() +to determine whether a session is resumed. + +The reference count of each certificate in the returned STACK_OF(X509) object +is not incremented and the returned stack may be invalidated by renegotiation. +If applications wish to use any certificates in the returned chain +indefinitely they must increase the reference counts using X509_up_ref() or +obtain a copy of the whole chain with X509_chain_up_ref(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +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 STACK_OF(X509) + +The return value points to the certificate chain presented by the peer. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_get_peer_certificate(3)>, L<X509_up_ref(3)>, +L<X509_chain_up_ref(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_peer_certificate.pod b/openssl-1.1.0h/doc/ssl/SSL_get_peer_certificate.pod new file mode 100644 index 0000000..57ed272 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_peer_certificate.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +SSL_get_peer_certificate - get the X509 certificate of the peer + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + X509 *SSL_get_peer_certificate(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_peer_certificate() returns a pointer to the X509 certificate the +peer presented. If the peer did not present a certificate, NULL is returned. + +=head1 NOTES + +Due to the protocol definition, a TLS/SSL server will always send a +certificate, if present. A client will only send a certificate when +explicitly requested to do so by the server (see +L<SSL_CTX_set_verify(3)>). If an anonymous cipher +is used, no certificates are sent. + +That a certificate is returned does not indicate information about the +verification state, use L<SSL_get_verify_result(3)> +to check the verification state. + +The reference count of the X509 object is incremented by one, so that it +will not be destroyed when the session containing the peer certificate is +freed. The X509 object must be explicitly freed using X509_free(). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +No certificate was presented by the peer or no connection was established. + +=item Pointer to an X509 certificate + +The return value points to the certificate presented by the peer. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_get_verify_result(3)>, +L<SSL_CTX_set_verify(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_psk_identity.pod b/openssl-1.1.0h/doc/ssl/SSL_get_psk_identity.pod new file mode 100644 index 0000000..d330eee --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_psk_identity.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_get_psk_identity, SSL_get_psk_identity_hint - get PSK client identity and hint + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_get_psk_identity_hint(const SSL *ssl); + const char *SSL_get_psk_identity(const SSL *ssl); + + +=head1 DESCRIPTION + +SSL_get_psk_identity_hint() is used to retrieve the PSK identity hint +used during the connection setup related to SSL object +B<ssl>. Similarly, SSL_get_psk_identity() is used to retrieve the PSK +identity used during the connection setup. + + +=head1 RETURN VALUES + +If non-B<NULL>, SSL_get_psk_identity_hint() returns the PSK identity +hint and SSL_get_psk_identity() returns the PSK identity. Both are +B<NULL>-terminated. SSL_get_psk_identity_hint() may return B<NULL> if +no PSK identity hint was used during the connection setup. + +Note that the return value is valid only during the lifetime of the +SSL object B<ssl>. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +Copyright 2005 Nokia. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_rbio.pod b/openssl-1.1.0h/doc/ssl/SSL_get_rbio.pod new file mode 100644 index 0000000..5ac4ca2 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_rbio.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +SSL_get_rbio, SSL_get_wbio - get BIO linked to an SSL object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + BIO *SSL_get_rbio(SSL *ssl); + BIO *SSL_get_wbio(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the +read or the write channel, which can be different. The reference count +of the BIO is not incremented. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +No BIO was connected to the SSL object + +=item Any other pointer + +The BIO linked to B<ssl>. + +=back + +=head1 SEE ALSO + +L<SSL_set_bio(3)>, L<ssl(3)> , L<bio(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_session.pod b/openssl-1.1.0h/doc/ssl/SSL_get_session.pod new file mode 100644 index 0000000..99936ad --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_session.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +SSL_get_session, SSL_get0_session, SSL_get1_session - retrieve TLS/SSL session data + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_SESSION *SSL_get_session(const SSL *ssl); + SSL_SESSION *SSL_get0_session(const SSL *ssl); + SSL_SESSION *SSL_get1_session(SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_session() returns a pointer to the B<SSL_SESSION> actually used in +B<ssl>. The reference count of the B<SSL_SESSION> is not incremented, so +that the pointer can become invalid by other operations. + +SSL_get0_session() is the same as SSL_get_session(). + +SSL_get1_session() is the same as SSL_get_session(), but the reference +count of the B<SSL_SESSION> is incremented by one. + +=head1 NOTES + +The ssl session contains all information required to re-establish the +connection without a new handshake. + +SSL_get0_session() returns a pointer to the actual session. As the +reference counter is not incremented, the pointer is only valid while +the connection is in use. If L<SSL_clear(3)> or +L<SSL_free(3)> is called, the session may be removed completely +(if considered bad), and the pointer obtained will become invalid. Even +if the session is valid, it can be removed at any time due to timeout +during L<SSL_CTX_flush_sessions(3)>. + +If the data is to be kept, SSL_get1_session() will increment the reference +count, so that the session will not be implicitly removed by other operations +but stays in memory. In order to remove the session +L<SSL_SESSION_free(3)> must be explicitly called once +to decrement the reference count again. + +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object's session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +There is no session available in B<ssl>. + +=item Pointer to an SSL_SESSION + +The return value points to the data of an SSL session. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_free(3)>, +L<SSL_clear(3)>, +L<SSL_SESSION_free(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_shared_sigalgs.pod b/openssl-1.1.0h/doc/ssl/SSL_get_shared_sigalgs.pod new file mode 100644 index 0000000..6a70e90 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_shared_sigalgs.pod @@ -0,0 +1,86 @@ +=pod + +=head1 NAME + +SSL_get_shared_sigalgs, SSL_get_sigalgs - get supported signature algorithms + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_get_shared_sigalgs(SSL *s, int idx, + int *psign, int *phash, int *psignhash, + unsigned char *rsig, unsigned char *rhash); + + int SSL_get_sigalgs(SSL *s, int idx, + int *psign, int *phash, int *psignhash, + unsigned char *rsig, unsigned char *rhash); + +=head1 DESCRIPTION + +SSL_get_shared_sigalgs() returns information about the shared signature +algorithms supported by peer B<s>. The parameter B<idx> indicates the index +of the shared signature algorithm to return starting from zero. The signature +algorithm NID is written to B<*psign>, the hash NID to B<*phash> and the +sign and hash NID to B<*psignhash>. The raw signature and hash values +are written to B<*rsig> and B<*rhash>. + +SSL_get_sigalgs() is similar to SSL_get_shared_sigalgs() except it returns +information about all signature algorithms supported by B<s> in the order +they were sent by the peer. + +=head1 RETURN VALUES + +SSL_get_shared_sigalgs() and SSL_get_sigalgs() return the number of +signature algorithms or B<0> if the B<idx> parameter is out of range. + +=head1 NOTES + +These functions are typically called for debugging purposes (to report +the peer's preferences) or where an application wants finer control over +certificate selection. Most applications will rely on internal handling +and will not need to call them. + +If an application is only interested in the highest preference shared +signature algorithm it can just set B<idx> to zero. + +Any or all of the parameters B<psign>, B<phash>, B<psignhash>, B<rsig> or +B<rhash> can be set to B<NULL> if the value is not required. By setting +them all to B<NULL> and setting B<idx> to zero the total number of +signature algorithms can be determined: which can be zero. + +These functions must be called after the peer has sent a list of supported +signature algorithms: after a client hello (for servers) or a certificate +request (for clients). They can (for example) be called in the certificate +callback. + +Only TLS 1.2 and DTLS 1.2 currently support signature algorithms. If these +functions are called on an earlier version of TLS or DTLS zero is returned. + +The shared signature algorithms returned by SSL_get_shared_sigalgs() are +ordered according to configuration and peer preferences. + +The raw values correspond to the on the wire form as defined by RFC5246 et al. +The NIDs are OpenSSL equivalents. For example if the peer sent sha256(4) and +rsa(1) then B<*rhash> would be 4, B<*rsign> 1, B<*phash> NID_sha256, B<*psig> +NID_rsaEncryption and B<*psighash> NID_sha256WithRSAEncryption. + +If a signature algorithm is not recognised the corresponding NIDs +will be set to B<NID_undef>. This may be because the value is not supported +or is not an appropriate combination (for example MD5 and DSA). + +=head1 SEE ALSO + +L<SSL_CTX_set_cert_cb(3)>, +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_verify_result.pod b/openssl-1.1.0h/doc/ssl/SSL_get_verify_result.pod new file mode 100644 index 0000000..3b8b657 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_verify_result.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +SSL_get_verify_result - get result of peer certificate verification + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + long SSL_get_verify_result(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_verify_result() returns the result of the verification of the +X509 certificate presented by the peer, if any. + +=head1 NOTES + +SSL_get_verify_result() can only return one error code while the verification +of a certificate can fail because of many reasons at the same time. Only +the last verification error that occurred during the processing is available +from SSL_get_verify_result(). + +The verification result is part of the established session and is restored +when a session is reused. + +=head1 BUGS + +If no peer certificate was presented, the returned result code is +X509_V_OK. This is because no verification error occurred, it does however +not indicate success. SSL_get_verify_result() is only useful in connection +with L<SSL_get_peer_certificate(3)>. + +=head1 RETURN VALUES + +The following return values can currently occur: + +=over 4 + +=item X509_V_OK + +The verification succeeded or no peer certificate was presented. + +=item Any other value + +Documented in L<verify(1)>. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_set_verify_result(3)>, +L<SSL_get_peer_certificate(3)>, +L<verify(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_get_version.pod b/openssl-1.1.0h/doc/ssl/SSL_get_version.pod new file mode 100644 index 0000000..23b6497 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_get_version.pod @@ -0,0 +1,67 @@ +=pod + +=head1 NAME + +SSL_get_version, SSL_is_dtls - get the protocol information of a connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_get_version(const SSL *ssl); + + int SSL_is_dtls(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_get_version() returns the name of the protocol used for the +connection B<ssl>. + +SSL_is_dtls() returns one if the connection is using DTLS, zero if not. + +=head1 RETURN VALUES + +SSL_get_version() returns one of the following strings: + +=over 4 + +=item SSLv3 + +The connection uses the SSLv3 protocol. + +=item TLSv1 + +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 + +This indicates that no version has been set (no connection established). + +=back + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 HISTORY + +SSL_is_dtls() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_library_init.pod b/openssl-1.1.0h/doc/ssl/SSL_library_init.pod new file mode 100644 index 0000000..85768a1 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_library_init.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +SSL_library_init, OpenSSL_add_ssl_algorithms +- initialize SSL library by registering algorithms + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_library_init(void); + + int OpenSSL_add_ssl_algorithms(void); + +=head1 DESCRIPTION + +SSL_library_init() registers the available SSL/TLS ciphers and digests. + +OpenSSL_add_ssl_algorithms() is a synonym for SSL_library_init() and is +implemented as a macro. + +=head1 NOTES + +SSL_library_init() must be called before any other action takes place. +SSL_library_init() is not reentrant. + +=head1 WARNING + +SSL_library_init() adds ciphers and digests used directly and indirectly by +SSL/TLS. + +=head1 RETURN VALUES + +SSL_library_init() always returns "1", so it is safe to discard the return +value. + +=head1 SEE ALSO + +L<ssl(7)>, +L<RAND_add(3)> + +=head1 HISTORY + +The SSL_library_init() and OpenSSL_add_ssl_algorithms() functions were +deprecated in OpenSSL 1.1.0 by OPENSSL_init_ssl(). + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_load_client_CA_file.pod b/openssl-1.1.0h/doc/ssl/SSL_load_client_CA_file.pod new file mode 100644 index 0000000..cc6a19c --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_load_client_CA_file.pod @@ -0,0 +1,71 @@ +=pod + +=head1 NAME + +SSL_load_client_CA_file - load certificate names from file + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file); + +=head1 DESCRIPTION + +SSL_load_client_CA_file() reads certificates from B<file> and returns +a STACK_OF(X509_NAME) with the subject names found. + +=head1 NOTES + +SSL_load_client_CA_file() reads a file of PEM formatted certificates and +extracts the X509_NAMES of the certificates found. While the name suggests +the specific usage as support function for +L<SSL_CTX_set_client_CA_list(3)>, +it is not limited to CA certificates. + +=head1 EXAMPLES + +Load names of CAs from file and use it as a client CA list: + + SSL_CTX *ctx; + STACK_OF(X509_NAME) *cert_names; + + ... + cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem"); + if (cert_names != NULL) + SSL_CTX_set_client_CA_list(ctx, cert_names); + else + error_handling(); + ... + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The operation failed, check out the error stack for the reason. + +=item Pointer to STACK_OF(X509_NAME) + +Pointer to the subject names of the successfully read certificates. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_new.pod b/openssl-1.1.0h/doc/ssl/SSL_new.pod new file mode 100644 index 0000000..a5a3ff9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_new.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_new, SSL_up_ref - create a new SSL structure for a connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL *SSL_new(SSL_CTX *ctx); + int SSL_up_ref(SSL *s); + +=head1 DESCRIPTION + +SSL_new() creates a new B<SSL> structure which is needed to hold the +data for a TLS/SSL connection. The new structure inherits the settings +of the underlying context B<ctx>: connection method, +options, verification settings, timeout settings. An B<SSL> structure is +reference counted. Creating an B<SSL> structure for the first time increments +the reference count. Freeing it (using SSL_free) decrements it. When the +reference count drops to zero, any memory or resources allocated to the B<SSL> +structure are freed. SSL_up_ref() increments the reference count for an +existing B<SSL> structure. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item NULL + +The creation of a new SSL structure failed. Check the error stack to +find out the reason. + +=item Pointer to an SSL structure + +The return value points to an allocated SSL structure. + +SSL_up_ref() returns 1 for success and 0 for failure. + +=back + +=head1 SEE ALSO + +L<SSL_free(3)>, L<SSL_clear(3)>, +L<SSL_CTX_set_options(3)>, +L<SSL_get_SSL_CTX(3)>, +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_pending.pod b/openssl-1.1.0h/doc/ssl/SSL_pending.pod new file mode 100644 index 0000000..f6ed565 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_pending.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +SSL_pending, SSL_has_pending - check for readable bytes buffered in an +SSL object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_pending(const SSL *ssl); + int SSL_has_pending(const SSL *s); + +=head1 DESCRIPTION + +Data is received in whole blocks known as records from the peer. A whole record +is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is +read by the application via a call to L<SSL_read(3)>. + +SSL_pending() returns the number of bytes which have been processed, buffered +and are available inside B<ssl> for immediate read. + +If the B<SSL> object's I<read_ahead> flag is set (see +L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current +record) may have been read containing more TLS/SSL records. This also applies to +DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These +additional bytes will be buffered by OpenSSL but will remain unprocessed until +they are needed. As these bytes are still in an unprocessed state SSL_pending() +will ignore them. Therefore it is possible for no more bytes to be readable from +the underlying BIO (because OpenSSL has already read them) and for SSL_pending() +to return 0, even though readable application data bytes are available (because +the data is in unprocessed buffered records). + +SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or +unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to +return 1, and then a subsequent call to SSL_read() to return no data because the +unprocessed buffered data when processed yielded no application data (for +example this can happen during renegotiation). It is also possible in this +scenario for SSL_has_pending() to continue to return 1 even after an SSL_read() +call because the buffered and unprocessed data is not yet processable (e.g. +because OpenSSL has only received a partial record so far). + +=head1 RETURN VALUES + +SSL_pending() returns the number of buffered and processed application data +bytes that are pending and are available for immediate read. SSL_has_pending() +returns 1 if there is buffered record data in the SSL object and 0 otherwise. + +=head1 SEE ALSO + +L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>, +L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)> + +=head1 HISTORY + +The SSL_has_pending() function was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_read.pod b/openssl-1.1.0h/doc/ssl/SSL_read.pod new file mode 100644 index 0000000..20ccf40 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_read.pod @@ -0,0 +1,121 @@ +=pod + +=head1 NAME + +SSL_read - read bytes from a TLS/SSL connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_read(SSL *ssl, void *buf, int num); + +=head1 DESCRIPTION + +SSL_read() tries to read B<num> bytes from the specified B<ssl> into the +buffer B<buf>. + +=head1 NOTES + +If necessary, SSL_read() will negotiate a TLS/SSL session, if +not already explicitly performed by L<SSL_connect(3)> or +L<SSL_accept(3)>. If the +peer requests a re-negotiation, it will be performed transparently during +the SSL_read() operation. The behaviour of SSL_read() depends on the +underlying BIO. + +For the transparent negotiation to succeed, the B<ssl> must have been +initialized to client or server mode. This is being done by calling +L<SSL_set_connect_state(3)> or SSL_set_accept_state() +before the first call to an SSL_read() or L<SSL_write(3)> +function. + +SSL_read() works based on the SSL/TLS records. The data are received in +records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a +record has been completely received, it can be processed (decryption and +check of integrity). Therefore data that was not retrieved at the last +call of SSL_read() can still be buffered inside the SSL layer and will be +retrieved on the next call to SSL_read(). If B<num> is higher than the +number of bytes buffered, SSL_read() will return with the bytes buffered. +If no more bytes are in the buffer, SSL_read() will trigger the processing +of the next record. Only when the record has been received and processed +completely, SSL_read() will return reporting success. At most the contents +of the record will be returned. As the size of an SSL/TLS record may exceed +the maximum packet size of the underlying transport (e.g. TCP), it may +be necessary to read several packets from the transport layer before the +record is complete and SSL_read() can succeed. + +If the underlying BIO is B<blocking>, SSL_read() will only return, once the +read operation has been finished or an error occurred, except when a +renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. +This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the +L<SSL_CTX_set_mode(3)> call. + +If the underlying BIO is B<non-blocking>, SSL_read() will also return +when the underlying BIO could not satisfy the needs of SSL_read() +to continue the operation. In this case a call to +L<SSL_get_error(3)> with the +return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a +call to SSL_read() can also cause write operations! The calling process +then must repeat the call after taking appropriate action to satisfy the +needs of SSL_read(). The action depends on the underlying BIO. When using a +non-blocking socket, nothing is to be done, but select() can be used to check +for the required condition. When using a buffering BIO, like a BIO pair, data +must be written into or retrieved out of the BIO before being able to continue. + +L<SSL_pending(3)> can be used to find out whether there +are buffered bytes available for immediate retrieval. In this case +SSL_read() can be called without blocking or actually receiving new +data from the underlying socket. + +=head1 WARNING + +When an SSL_read() operation has to be repeated because of +B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated +with the same arguments. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E<gt> 0 + +The read operation was successful. +The return value is the number of bytes actually read from the TLS/SSL +connection. + +=item Z<><= 0 + +The read operation was not successful, because either the connection was closed, +an error occurred or action must be taken by the calling process. +Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. + +Old documentation indicated a difference between 0 and -1, and that -1 was +retryable. +You should instead call SSL_get_error() to find out if it's retryable. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_write(3)>, +L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>, +L<SSL_connect(3)>, L<SSL_accept(3)> +L<SSL_set_connect_state(3)>, +L<SSL_pending(3)>, +L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>, +L<ssl(3)>, L<bio(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_rstate_string.pod b/openssl-1.1.0h/doc/ssl/SSL_rstate_string.pod new file mode 100644 index 0000000..7775913 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_rstate_string.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +SSL_rstate_string, SSL_rstate_string_long - get textual description of state of an SSL object during read operation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_rstate_string(SSL *ssl); + const char *SSL_rstate_string_long(SSL *ssl); + +=head1 DESCRIPTION + +SSL_rstate_string() returns a 2 letter string indicating the current read state +of the SSL object B<ssl>. + +SSL_rstate_string_long() returns a string indicating the current read state of +the SSL object B<ssl>. + +=head1 NOTES + +When performing a read operation, the SSL/TLS engine must parse the record, +consisting of header and body. When working in a blocking environment, +SSL_rstate_string[_long]() should always return "RD"/"read done". + +This function should only seldom be needed in applications. + +=head1 RETURN VALUES + +SSL_rstate_string() and SSL_rstate_string_long() can return the following +values: + +=over 4 + +=item "RH"/"read header" + +The header of the record is being evaluated. + +=item "RB"/"read body" + +The body of the record is being evaluated. + +=item "RD"/"read done" + +The record has been completely processed. + +=item "unknown"/"unknown" + +The read state is unknown. This should never happen. + +=back + +=head1 SEE ALSO + +L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_session_reused.pod b/openssl-1.1.0h/doc/ssl/SSL_session_reused.pod new file mode 100644 index 0000000..eda66b2 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_session_reused.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +SSL_session_reused - query whether a reused session was negotiated during handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_session_reused(SSL *ssl); + +=head1 DESCRIPTION + +Query, whether a reused session was negotiated during the handshake. + +=head1 NOTES + +During the negotiation, a client can propose to reuse a session. The server +then looks up the session in its cache. If both client and server agree +on the session, it will be reused and a flag is being set that can be +queried by the application. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item Z<>0 + +A new session was negotiated. + +=item Z<>1 + +A session was reused. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_set_session(3)>, +L<SSL_CTX_set_session_cache_mode(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_set1_host.pod b/openssl-1.1.0h/doc/ssl/SSL_set1_host.pod new file mode 100644 index 0000000..3339a0e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set1_host.pod @@ -0,0 +1,121 @@ +=pod + +=head1 NAME + +SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername - +SSL server verification parameters + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_set1_host(SSL *s, const char *hostname); + int SSL_add1_host(SSL *s, const char *hostname); + void SSL_set_hostflags(SSL *s, unsigned int flags); + const char *SSL_get0_peername(SSL *s); + +=head1 DESCRIPTION + +These functions configure server hostname checks in the SSL client. + +SSL_set1_host() sets the expected DNS hostname to B<name> clearing +any previously specified host name or names. If B<name> is NULL, +or the empty string the list of hostnames is cleared, and name +checks are not performed on the peer certificate. When a non-empty +B<name> is specified, certificate verification automatically checks +the peer hostname via L<X509_check_host(3)> with B<flags> as specified +via SSL_set_hostflags(). Clients that enable DANE TLSA authentication +via L<SSL_dane_enable(3)> should leave it to that function to set +the primary reference identifier of the peer, and should not call +SSL_set1_host(). + +SSL_add1_host() adds B<name> as an additional reference identifier +that can match the peer's certificate. Any previous names set via +SSL_set1_host() or SSL_add1_host() are retained, no change is made +if B<name> is NULL or empty. When multiple names are configured, +the peer is considered verified when any name matches. This function +is required for DANE TLSA in the presence of service name indirection +via CNAME, MX or SRV records as specified in RFC7671, RFC7672 or +RFC7673. + +SSL_set_hostflags() sets the B<flags> that will be passed to +L<X509_check_host(3)> when name checks are applicable, by default +the B<flags> value is 0. See L<X509_check_host(3)> for the list +of available flags and their meaning. + +SSL_get0_peername() returns the DNS hostname or subject CommonName +from the peer certificate that matched one of the reference +identifiers. When wildcard matching is not disabled, the name +matched in the peer certificate may be a wildcard name. When one +of the reference identifiers configured via SSL_set1_host() or +SSL_add1_host() starts with ".", which indicates a parent domain prefix +rather than a fixed name, the matched peer name may be a sub-domain +of the reference identifier. The returned string is allocated by +the library and is no longer valid once the associated B<ssl> handle +is cleared or freed, or a renegotiation takes place. Applications +must not free the return value. + +SSL clients are advised to use these functions in preference to +explicitly calling L<X509_check_host(3)>. Hostname checks are out +of scope with the RFC7671 DANE-EE(3) certificate usage, and the +internal check will be suppressed as appropriate when DANE is +enabled. + +=head1 RETURN VALUES + +SSL_set1_host() and SSL_add1_host() return 1 for success and 0 for +failure. + +SSL_get0_peername() returns NULL if peername verification is not +applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was +matched. Otherwise, it returns the matched peername. To determine +whether verification succeeded call L<SSL_get_verify_result(3)>. + +=head1 EXAMPLE + +Suppose "smtp.example.com" is the MX host of the domain "example.com". +The calls below will arrange to match either the MX hostname or the +destination domain name in the SMTP server certificate. Wildcards +are supported, but must match the entire label. The actual name +matched in the certificate (which might be a wildcard) is retrieved, +and must be copied by the application if it is to be retained beyond +the lifetime of the SSL connection. + + SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); + if (!SSL_set1_host(ssl, "smtp.example.com")) { + /* handle error */ + } + if (!SSL_add1_host(ssl, "example.com")) { + /* handle error */ + } + + /* XXX: Perform SSL_connect() handshake and handle errors here */ + + if (SSL_get_verify_result(ssl) == X509_V_OK) { + const char *peername = SSL_get0_peername(ssl); + + if (peername != NULL) { + /* Name checks were in scope and matched the peername */ + } + } + +=head1 SEE ALSO + +L<X509_check_host(3)>, +L<SSL_get_verify_result(3)>. +L<SSL_dane_enable(3)>. + +=head1 HISTORY + +These functions were first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_set_bio.pod b/openssl-1.1.0h/doc/ssl/SSL_set_bio.pod new file mode 100644 index 0000000..4230940 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_bio.pod @@ -0,0 +1,108 @@ +=pod + +=head1 NAME + +SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); + void SSL_set0_rbio(SSL *s, BIO *rbio); + void SSL_set0_wbio(SSL *s, BIO *wbio); + +=head1 DESCRIPTION + +SSL_set0_rbio() connects the BIO B<rbio> for the read operations of the B<ssl> +object. The SSL engine inherits the behaviour of B<rbio>. If the BIO is +non-blocking then the B<ssl> object will also have non-blocking behaviour. This +function transfers ownership of B<rbio> to B<ssl>. It will be automatically +freed using L<BIO_free_all(3)> when the B<ssl> is freed. On calling this +function, any existing B<rbio> that was previously set will also be freed via a +call to L<BIO_free_all(3)> (this includes the case where the B<rbio> is set to +the same value as previously). + +SSL_set0_wbio() works in the same as SSL_set0_rbio() except that it connects +the BIO B<wbio> for the write operations of the B<ssl> object. Note that if the +rbio and wbio are the same then SSL_set0_rbio() and SSL_set0_wbio() each take +ownership of one reference. Therefore it may be necessary to increment the +number of references available using L<BIO_up_ref(3)> before calling the set0 +functions. + +SSL_set_bio() does a similar job as SSL_set0_rbio() and SSL_set0_wbio() except +that it connects both the B<rbio> and the B<wbio> at the same time. This +function transfers the ownership of B<rbio> and B<wbio> to B<ssl> except that +the rules for this are much more complex. For this reason this function is +considered a legacy function and SSL_set0_rbio() and SSL_set0_wbio() should be +used in preference. The ownership rules are as follows: + +=over 2 + +=item * + +If neither the rbio or wbio have changed from their previous values then nothing +is done. + +=item * + +If the rbio and wbio parameters are different and both are different to their +previously set values then one reference is consumed for the rbio and one +reference is consumed for the wbio. + +=item * + +If the rbio and wbio parameters are the same and the rbio is not the same as the +previously set value then one reference is consumed. + +=item * + +If the rbio and wbio parameters are the same and the rbio is the same as the +previously set value, then no additional references are consumed. + +=item * + +If the rbio and wbio parameters are different and the rbio is the same as the +previously set value then one reference is consumed for the wbio and no +references are consumed for the rbio. + +=item * + +If the rbio and wbio parameters are different and the wbio is the same as the +previously set value and the old rbio and wbio values were the same as each +other then one reference is consumed for the rbio and no references are consumed +for the wbio. + +=item * + +If the rbio and wbio parameters are different and the wbio is the same as the +previously set value and the old rbio and wbio values were different to each +other then one reference is consumed for the rbio and one reference is consumed +for the wbio. + +=back + +=head1 RETURN VALUES + +SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail. + +=head1 SEE ALSO + +L<SSL_get_rbio(3)>, +L<SSL_connect(3)>, L<SSL_accept(3)>, +L<SSL_shutdown(3)>, L<ssl(7)>, L<bio(7)> + +=head1 HISTORY + +SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_set_connect_state.pod b/openssl-1.1.0h/doc/ssl/SSL_set_connect_state.pod new file mode 100644 index 0000000..9031aa7 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_connect_state.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +SSL_set_connect_state, SSL_set_accept_state - prepare SSL object to work in client or server mode + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_connect_state(SSL *ssl); + + void SSL_set_accept_state(SSL *ssl); + +=head1 DESCRIPTION + +SSL_set_connect_state() sets B<ssl> to work in client mode. + +SSL_set_accept_state() sets B<ssl> to work in server mode. + +=head1 NOTES + +When the SSL_CTX object was created with L<SSL_CTX_new(3)>, +it was either assigned a dedicated client method, a dedicated server +method, or a generic method, that can be used for both client and +server connections. (The method might have been changed with +L<SSL_CTX_set_ssl_version(3)> or +SSL_set_ssl_method(3).) + +When beginning a new handshake, the SSL engine must know whether it must +call the connect (client) or accept (server) routines. Even though it may +be clear from the method chosen, whether client or server mode was +requested, the handshake routines must be explicitly set. + +When using the L<SSL_connect(3)> or +L<SSL_accept(3)> routines, the correct handshake +routines are automatically set. When performing a transparent negotiation +using L<SSL_write(3)> or L<SSL_read(3)>, the +handshake routines must be explicitly set in advance using either +SSL_set_connect_state() or SSL_set_accept_state(). + +=head1 RETURN VALUES + +SSL_set_connect_state() and SSL_set_accept_state() do not return diagnostic +information. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_new(3)>, L<SSL_CTX_new(3)>, +LL<SSL_connect(3)>, L<SSL_accept(3)>, +L<SSL_write(3)>, L<SSL_read(3)>, +L<SSL_do_handshake(3)>, +L<SSL_CTX_set_ssl_version(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_set_fd.pod b/openssl-1.1.0h/doc/ssl/SSL_set_fd.pod new file mode 100644 index 0000000..e1f9988 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_fd.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +SSL_set_fd, SSL_set_rfd, SSL_set_wfd - connect the SSL object with a file descriptor + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_set_fd(SSL *ssl, int fd); + int SSL_set_rfd(SSL *ssl, int fd); + int SSL_set_wfd(SSL *ssl, int fd); + +=head1 DESCRIPTION + +SSL_set_fd() sets the file descriptor B<fd> as the input/output facility +for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the +socket file descriptor of a network connection. + +When performing the operation, a B<socket BIO> is automatically created to +interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine +inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will +also have non-blocking behaviour. + +If there was already a BIO connected to B<ssl>, BIO_free() will be called +(for both the reading and writing side, if different). + +SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only +for the read channel or the write channel, which can be set independently. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item Z<>0 + +The operation failed. Check the error stack to find out why. + +=item Z<>1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<SSL_get_fd(3)>, L<SSL_set_bio(3)>, +L<SSL_connect(3)>, L<SSL_accept(3)>, +L<SSL_shutdown(3)>, L<ssl(3)> , L<bio(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_set_session.pod b/openssl-1.1.0h/doc/ssl/SSL_set_session.pod new file mode 100644 index 0000000..1de533f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_session.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_set_session(SSL *ssl, SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_set_session() sets B<session> to be used when the TLS/SSL connection +is to be established. SSL_set_session() is only useful for TLS/SSL clients. +When the session is set, the reference count of B<session> is incremented +by 1. If the session is not reused, the reference count is decremented +again during SSL_connect(). Whether the session was reused can be queried +with the L<SSL_session_reused(3)> call. + +If there is already a session set inside B<ssl> (because it was set with +SSL_set_session() before or because the same B<ssl> was already used for +a connection), SSL_SESSION_free() will be called for that session. If that old +session is still B<open>, it is considered bad and will be removed from the +session cache (if used). A session is considered open, if L<SSL_shutdown(3)> was +not called for the connection (or at least L<SSL_set_shutdown(3)> was used to +set the SSL_SENT_SHUTDOWN state). + +=head1 NOTES + +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object's session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item Z<>0 + +The operation failed; check the error stack to find out the reason. + +=item Z<>1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_SESSION_free(3)>, +L<SSL_get_session(3)>, +L<SSL_session_reused(3)>, +L<SSL_CTX_set_session_cache_mode(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_set_shutdown.pod b/openssl-1.1.0h/doc/ssl/SSL_set_shutdown.pod new file mode 100644 index 0000000..ecdf60c --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_shutdown.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_shutdown(SSL *ssl, int mode); + + int SSL_get_shutdown(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_set_shutdown() sets the shutdown state of B<ssl> to B<mode>. + +SSL_get_shutdown() returns the shutdown mode of B<ssl>. + +=head1 NOTES + +The shutdown state of an ssl connection is a bitmask of: + +=over 4 + +=item Z<>0 + +No shutdown setting, yet. + +=item SSL_SENT_SHUTDOWN + +A "close notify" shutdown alert was sent to the peer, the connection is being +considered closed and the session is closed and correct. + +=item SSL_RECEIVED_SHUTDOWN + +A shutdown alert was received form the peer, either a normal "close notify" +or a fatal error. + +=back + +SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time. + +The shutdown state of the connection is used to determine the state of +the ssl session. If the session is still open, when +L<SSL_clear(3)> or L<SSL_free(3)> is called, +it is considered bad and removed according to RFC2246. +The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN +(according to the TLS RFC, it is acceptable to only send the "close notify" +alert but to not wait for the peer's answer, when the underlying connection +is closed). +SSL_set_shutdown() can be used to set this state without sending a +close alert to the peer (see L<SSL_shutdown(3)>). + +If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set, +for setting SSL_SENT_SHUTDOWN the application must however still call +L<SSL_shutdown(3)> or SSL_set_shutdown() itself. + +=head1 RETURN VALUES + +SSL_set_shutdown() does not return diagnostic information. + +SSL_get_shutdown() returns the current setting. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_shutdown(3)>, +L<SSL_CTX_set_quiet_shutdown(3)>, +L<SSL_clear(3)>, L<SSL_free(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_set_verify_result.pod b/openssl-1.1.0h/doc/ssl/SSL_set_verify_result.pod new file mode 100644 index 0000000..8738d78 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_set_verify_result.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_set_verify_result - override result of peer certificate verification + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + void SSL_set_verify_result(SSL *ssl, long verify_result); + +=head1 DESCRIPTION + +SSL_set_verify_result() sets B<verify_result> of the object B<ssl> to be the +result of the verification of the X509 certificate presented by the peer, +if any. + +=head1 NOTES + +SSL_set_verify_result() overrides the verification result. It only changes +the verification result of the B<ssl> object. It does not become part of the +established session, so if the session is to be reused later, the original +value will reappear. + +The valid codes for B<verify_result> are documented in L<verify(1)>. + +=head1 RETURN VALUES + +SSL_set_verify_result() does not provide a return value. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_get_verify_result(3)>, +L<SSL_get_peer_certificate(3)>, +L<verify(1)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_shutdown.pod b/openssl-1.1.0h/doc/ssl/SSL_shutdown.pod new file mode 100644 index 0000000..e8ec454 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_shutdown.pod @@ -0,0 +1,132 @@ +=pod + +=head1 NAME + +SSL_shutdown - shut down a TLS/SSL connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_shutdown(SSL *ssl); + +=head1 DESCRIPTION + +SSL_shutdown() shuts down an active TLS/SSL connection. It sends the +"close notify" shutdown alert to the peer. + +=head1 NOTES + +SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. +Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and +a currently open session is considered closed and good and will be kept in the +session cache for further reuse. + +The shutdown procedure consists of 2 steps: the sending of the "close notify" +shutdown alert and the reception of the peer's "close notify" shutdown +alert. According to the TLS standard, it is acceptable for an application +to only send its shutdown alert and then close the underlying connection +without waiting for the peer's response (this way resources can be saved, +as the process can already terminate or serve another connection). +When the underlying connection shall be used for more communications, the +complete shutdown procedure (bidirectional "close notify" alerts) must be +performed, so that the peers stay synchronized. + +SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step +behaviour. + +=over 4 + +=item When the application is the first party to send the "close notify" +alert, SSL_shutdown() will only send the alert and then set the +SSL_SENT_SHUTDOWN flag (so that the session is considered good and will +be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional +shutdown is enough (the underlying connection shall be closed anyway), this +first call to SSL_shutdown() is sufficient. In order to complete the +bidirectional shutdown handshake, SSL_shutdown() must be called again. +The second call will make SSL_shutdown() wait for the peer's "close notify" +shutdown alert. On success, the second call to SSL_shutdown() will return +with 1. + +=item If the peer already sent the "close notify" alert B<and> it was +already processed implicitly inside another function +(L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. +SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN +flag and will immediately return with 1. +Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the +SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call. + +=back + +It is therefore recommended, to check the return value of SSL_shutdown() +and call SSL_shutdown() again, if the bidirectional shutdown is not yet +complete (return value of the first call is 0). + +The behaviour of SSL_shutdown() additionally depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the +handshake step has been finished or an error occurred. + +If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return +when the underlying BIO could not satisfy the needs of SSL_shutdown() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_shutdown(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +SSL_shutdown() can be modified to only set the connection to "shutdown" +state but not actually send the "close notify" alert messages, +see L<SSL_CTX_set_quiet_shutdown(3)>. +When "quiet shutdown" is enabled, SSL_shutdown() will always succeed +and return 1. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=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)> 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 E<lt>0 + +The shutdown was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. It can also occur if +action is need to continue the operation for non-blocking BIOs. +Call L<SSL_get_error(3)> with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_connect(3)>, +L<SSL_accept(3)>, L<SSL_set_shutdown(3)>, +L<SSL_CTX_set_quiet_shutdown(3)>, +L<SSL_clear(3)>, L<SSL_free(3)>, +L<ssl(3)>, L<bio(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_state_string.pod b/openssl-1.1.0h/doc/ssl/SSL_state_string.pod new file mode 100644 index 0000000..a2f59e8 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_state_string.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +SSL_state_string, SSL_state_string_long - get textual description of state of an SSL object + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + const char *SSL_state_string(const SSL *ssl); + const char *SSL_state_string_long(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_state_string() returns a 6 letter string indicating the current state +of the SSL object B<ssl>. + +SSL_state_string_long() returns a string indicating the current state of +the SSL object B<ssl>. + +=head1 NOTES + +During its use, an SSL objects passes several states. The state is internally +maintained. Querying the state information is not very informative before +or when a connection has been established. It however can be of significant +interest during the handshake. + +When using non-blocking sockets, the function call performing the handshake +may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition, +so that SSL_state_string[_long]() may be called. + +For both blocking or non-blocking sockets, the details state information +can be used within the info_callback function set with the +SSL_set_info_callback() call. + +=head1 RETURN VALUES + +Detailed description of possible states to be included later. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_CTX_set_info_callback(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_want.pod b/openssl-1.1.0h/doc/ssl/SSL_want.pod new file mode 100644 index 0000000..e179d6b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_want.pod @@ -0,0 +1,103 @@ +=pod + +=head1 NAME + +SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup, +SSL_want_async, SSL_want_async_job - obtain state information TLS/SSL I/O +operation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_want(const SSL *ssl); + int SSL_want_nothing(const SSL *ssl); + int SSL_want_read(const SSL *ssl); + int SSL_want_write(const SSL *ssl); + int SSL_want_x509_lookup(const SSL *ssl); + int SSL_want_async(const SSL *ssl); + int SSL_want_async_job(const SSL *ssl); + +=head1 DESCRIPTION + +SSL_want() returns state information for the SSL object B<ssl>. + +The other SSL_want_*() calls are shortcuts for the possible states returned +by SSL_want(). + +=head1 NOTES + +SSL_want() examines the internal state information of the SSL object. Its +return values are similar to that of L<SSL_get_error(3)>. +Unlike L<SSL_get_error(3)>, which also evaluates the +error queue, the results are obtained by examining an internal state flag +only. The information must therefore only be used for normal operation under +non-blocking I/O. Error conditions are not handled and must be treated +using L<SSL_get_error(3)>. + +The result returned by SSL_want() should always be consistent with +the result of L<SSL_get_error(3)>. + +=head1 RETURN VALUES + +The following return values can currently occur for SSL_want(): + +=over 4 + +=item SSL_NOTHING + +There is no data to be written or to be read. + +=item SSL_WRITING + +There are data in the SSL buffer that must be written to the underlying +B<BIO> layer in order to complete the actual SSL_*() operation. +A call to L<SSL_get_error(3)> should return +SSL_ERROR_WANT_WRITE. + +=item SSL_READING + +More data must be read from the underlying B<BIO> layer in order to +complete the actual SSL_*() operation. +A call to L<SSL_get_error(3)> should return +SSL_ERROR_WANT_READ. + +=item SSL_X509_LOOKUP + +The operation did not complete because an application callback set by +SSL_CTX_set_client_cert_cb() has asked to be called again. +A call to L<SSL_get_error(3)> should return +SSL_ERROR_WANT_X509_LOOKUP. + +=item SSL_ASYNC_PAUSED + +An asynchronous operation partially completed and was then paused. See +L<SSL_get_all_async_fds(3)>. A call to L<SSL_get_error(3)> should return +SSL_ERROR_WANT_ASYNC. + +=item SSL_ASYNC_NO_JOBS + +The asynchronous job could not be started because there were no async jobs +available in the pool (see ASYNC_init_thread(3)). A call to L<SSL_get_error(3)> +should return SSL_ERROR_WANT_ASYNC_JOB. + +=back + +SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup(), +SSL_want_async() and SSL_want_async_job() return 1, when the corresponding +condition is true or 0 otherwise. + +=head1 SEE ALSO + +L<ssl(3)>, L<err(3)>, L<SSL_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_write.pod b/openssl-1.1.0h/doc/ssl/SSL_write.pod new file mode 100644 index 0000000..ef3b92a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_write.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +SSL_write - write bytes to a TLS/SSL connection + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_write(SSL *ssl, const void *buf, int num); + +=head1 DESCRIPTION + +SSL_write() writes B<num> bytes from the buffer B<buf> into the specified +B<ssl> connection. + +=head1 NOTES + +If necessary, SSL_write() will negotiate a TLS/SSL session, if +not already explicitly performed by L<SSL_connect(3)> or +L<SSL_accept(3)>. If the +peer requests a re-negotiation, it will be performed transparently during +the SSL_write() operation. The behaviour of SSL_write() depends on the +underlying BIO. + +For the transparent negotiation to succeed, the B<ssl> must have been +initialized to client or server mode. This is being done by calling +L<SSL_set_connect_state(3)> or SSL_set_accept_state() +before the first call to an L<SSL_read(3)> or SSL_write() function. + +If the underlying BIO is B<blocking>, SSL_write() will only return, once the +write operation has been finished or an error occurred, except when a +renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. +This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the +L<SSL_CTX_set_mode(3)> call. + +If the underlying BIO is B<non-blocking>, SSL_write() will also return, +when the underlying BIO could not satisfy the needs of SSL_write() +to continue the operation. In this case a call to +L<SSL_get_error(3)> with the +return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a +call to SSL_write() can also cause read operations! The calling process +then must repeat the call after taking appropriate action to satisfy the +needs of SSL_write(). The action depends on the underlying BIO. When using a +non-blocking socket, nothing is to be done, but select() can be used to check +for the required condition. When using a buffering BIO, like a BIO pair, data +must be written into or retrieved out of the BIO before being able to continue. + +SSL_write() will only return with success, when the complete contents +of B<buf> of length B<num> has been written. This default behaviour +can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of +L<SSL_CTX_set_mode(3)>. When this flag is set, +SSL_write() will also return with success, when a partial write has been +successfully completed. In this case the SSL_write() operation is considered +completed. The bytes are sent and a new SSL_write() operation with a new +buffer (with the already sent bytes removed) must be started. +A partial write is performed with the size of a message block, which is +16kB for SSLv3/TLSv1. + +=head1 WARNING + +When an SSL_write() operation has to be repeated because of +B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated +with the same arguments. + +When calling SSL_write() with num=0 bytes to be sent the behaviour is +undefined. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item E<gt> 0 + +The write operation was successful, the return value is the number of +bytes actually written to the TLS/SSL connection. + +=item Z<><= 0 + +The write operation was not successful, because either the connection was +closed, an error occurred or action must be taken by the calling process. +Call SSL_get_error() with the return value B<ret> to find out the reason. + +Old documentation indicated a difference between 0 and -1, and that -1 was +retryable. +You should instead call SSL_get_error() to find out if it's retryable. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)>, L<SSL_read(3)>, +L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>, +L<SSL_connect(3)>, L<SSL_accept(3)> +L<SSL_set_connect_state(3)>, +L<ssl(3)>, L<bio(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/d2i_SSL_SESSION.pod b/openssl-1.1.0h/doc/ssl/d2i_SSL_SESSION.pod new file mode 100644 index 0000000..d6b1707 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/d2i_SSL_SESSION.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length); + int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); + +=head1 DESCRIPTION + +These functions decode and encode an SSL_SESSION object. +For encoding details see L<d2i_X509(3)>. + +SSL_SESSION objects keep internal link information about the session cache +list, when being inserted into one SSL_CTX object's session cache. +One SSL_SESSION object, regardless of its reference count, must therefore +only be used with one SSL_CTX object (and the SSL objects created +from this SSL_CTX object). + +=head1 RETURN VALUES + +d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION +object. In case of failure the NULL-pointer is returned and the error message +can be retrieved from the error stack. + +i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. +When the session is not valid, B<0> is returned and no operation is performed. + +=head1 SEE ALSO + +L<ssl(3)>, L<SSL_SESSION_free(3)>, +L<SSL_CTX_sess_set_get_cb(3)>, +L<d2i_X509(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/ssl.pod b/openssl-1.1.0h/doc/ssl/ssl.pod new file mode 100644 index 0000000..4d91907 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/ssl.pod @@ -0,0 +1,843 @@ +=pod + +=for comment openssl_manual_section:7 + +=head1 NAME + +ssl - OpenSSL SSL/TLS library + +=head1 SYNOPSIS + +See the individual manual pages for details. + +=head1 DESCRIPTION + +The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and +Transport Layer Security (TLS v1) protocols. It provides a rich API which is +documented here. + +Then an B<SSL_CTX> object is created as a framework to establish +TLS/SSL enabled connections (see L<SSL_CTX_new(3)>). +Various options regarding certificates, algorithms etc. can be set +in this object. + +When a network connection has been created, it can be assigned to an +B<SSL> object. After the B<SSL> object has been created using +L<SSL_new(3)>, L<SSL_set_fd(3)> or +L<SSL_set_bio(3)> can be used to associate the network +connection with the object. + +Then the TLS/SSL handshake is performed using +L<SSL_accept(3)> or L<SSL_connect(3)> +respectively. +L<SSL_read(3)> and L<SSL_write(3)> are +used to read and write data on the TLS/SSL connection. +L<SSL_shutdown(3)> can be used to shut down the +TLS/SSL connection. + +=head1 DATA STRUCTURES + +Currently the OpenSSL B<ssl> library functions deals with the following data +structures: + +=over 4 + +=item B<SSL_METHOD> (SSL Method) + +That's a dispatch structure describing the internal B<ssl> library +methods/functions which implement the various protocol versions (SSLv3 +TLSv1, ...). It's needed to create an B<SSL_CTX>. + +=item B<SSL_CIPHER> (SSL Cipher) + +This structure holds the algorithm information for a particular cipher which +are a core part of the SSL/TLS protocol. The available ciphers are configured +on a B<SSL_CTX> basis and the actually used ones are then part of the +B<SSL_SESSION>. + +=item B<SSL_CTX> (SSL Context) + +That's the global context structure which is created by a server or client +once per program life-time and which holds mainly default values for the +B<SSL> structures which are later created for the connections. + +=item B<SSL_SESSION> (SSL Session) + +This is a structure containing the current TLS/SSL session details for a +connection: B<SSL_CIPHER>s, client and server certificates, keys, etc. + +=item B<SSL> (SSL Connection) + +That's the main SSL/TLS structure which is created by a server or client per +established connection. This actually is the core structure in the SSL API. +Under run-time the application usually deals with this structure which has +links to mostly all other structures. + +=back + + +=head1 HEADER FILES + +Currently the OpenSSL B<ssl> library provides the following C header files +containing the prototypes for the data structures and functions: + +=over 4 + +=item B<ssl.h> + +That's the common header file for the SSL/TLS API. Include it into your +program to make the API of the B<ssl> library available. It internally +includes both more private SSL headers and headers from the B<crypto> library. +Whenever you need hard-core details on the internals of the SSL API, look +inside this header file. + +OPENSSL_VERSION_AT_LEAST(major,minor) can be +used in C<#if> statements in order to determine which version of the library is +being used. This can be used to either enable optional features at compile +time, or work around issues with a previous version. +See L<OPENSSL_VERSION_NUMBER(3)>. + +=item B<ssl2.h> + +Unused. Present for backwards compatibility only. + +=item B<ssl3.h> + +That's the sub header file dealing with the SSLv3 protocol only. +I<Usually you don't have to include it explicitly because +it's already included by ssl.h>. + +=item B<tls1.h> + +That's the sub header file dealing with the TLSv1 protocol only. +I<Usually you don't have to include it explicitly because +it's already included by ssl.h>. + +=back + +=head1 API FUNCTIONS + +Currently the OpenSSL B<ssl> library exports 214 API functions. +They are documented in the following: + +=head2 Dealing with Protocol Methods + +Here we document the various API functions which deal with the SSL/TLS +protocol methods defined in B<SSL_METHOD> structures. + +=over 4 + +=item const SSL_METHOD *B<TLS_method>(void); + +Constructor for the I<version-flexible> SSL_METHOD structure for clients, +servers or both. +See L<SSL_CTX_new(3)> for details. + +=item const SSL_METHOD *B<TLS_client_method>(void); + +Constructor for the I<version-flexible> SSL_METHOD structure for clients. + +=item const SSL_METHOD *B<TLS_server_method>(void); + +Constructor for the I<version-flexible> SSL_METHOD structure for servers. + +=item const SSL_METHOD *B<TLSv1_2_method>(void); + +Constructor for the TLSv1.2 SSL_METHOD structure for clients, servers or both. + +=item const SSL_METHOD *B<TLSv1_2_client_method>(void); + +Constructor for the TLSv1.2 SSL_METHOD structure for clients. + +=item const SSL_METHOD *B<TLSv1_2_server_method>(void); + +Constructor for the TLSv1.2 SSL_METHOD structure for servers. + +=item const SSL_METHOD *B<TLSv1_1_method>(void); + +Constructor for the TLSv1.1 SSL_METHOD structure for clients, servers or both. + +=item const SSL_METHOD *B<TLSv1_1_client_method>(void); + +Constructor for the TLSv1.1 SSL_METHOD structure for clients. + +=item const SSL_METHOD *B<TLSv1_1_server_method>(void); + +Constructor for the TLSv1.1 SSL_METHOD structure for servers. + +=item const SSL_METHOD *B<TLSv1_method>(void); + +Constructor for the TLSv1 SSL_METHOD structure for clients, servers or both. + +=item const SSL_METHOD *B<TLSv1_client_method>(void); + +Constructor for the TLSv1 SSL_METHOD structure for clients. + +=item const SSL_METHOD *B<TLSv1_server_method>(void); + +Constructor for the TLSv1 SSL_METHOD structure for servers. + +=item const SSL_METHOD *B<SSLv3_method>(void); + +Constructor for the SSLv3 SSL_METHOD structure for clients, servers or both. + +=item const SSL_METHOD *B<SSLv3_client_method>(void); + +Constructor for the SSLv3 SSL_METHOD structure for clients. + +=item const SSL_METHOD *B<SSLv3_server_method>(void); + +Constructor for the SSLv3 SSL_METHOD structure for servers. + +=back + +=head2 Dealing with Ciphers + +Here we document the various API functions which deal with the SSL/TLS +ciphers defined in B<SSL_CIPHER> structures. + +=over 4 + +=item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len); + +Write a string to I<buf> (with a maximum size of I<len>) containing a human +readable description of I<cipher>. Returns I<buf>. + +=item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits); + +Determine the number of bits in I<cipher>. Because of export crippled ciphers +there are two bits: The bits the algorithm supports in general (stored to +I<alg_bits>) and the bits which are actually used (the return value). + +=item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher); + +Return the internal name of I<cipher> as a string. These are the various +strings defined by the I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx> +definitions in the header files. + +=item const char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher); + +Returns a string like "C<SSLv3>" or "C<TLSv1.2>" which indicates the +SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined +in the specification the first time). + +=back + +=head2 Dealing with Protocol Contexts + +Here we document the various API functions which deal with the SSL/TLS +protocol context defined in the B<SSL_CTX> structure. + +=over 4 + +=item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x); + +=item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509); + +=item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c); + +=item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx); + +=item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg); + +=item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t); + +=item void B<SSL_CTX_free>(SSL_CTX *a); + +=item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx); + +=item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx); + +=item STACK *B<SSL_CTX_get_ciphers>(const SSL_CTX *ctx); + +=item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx); + +=item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); + +=item void B<SSL_CTX_get_default_read_ahead>(SSL_CTX *ctx); + +=item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx); + +=item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) + +=item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret); + +=item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx); + +=item void B<SSL_CTX_get_read_ahead>(SSL_CTX *ctx); + +=item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx); + +=item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx); + +=item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx); + +=item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx); + +=item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, const char *CAfile, const char *CApath); + +=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth); + +=item int SSL_CTX_up_ref(SSL_CTX *ctx); + +=item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c); + +=item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx); + +=item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy); + +=item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess); + +=item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess); + +=item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx); + +=item int B<SSL_CTX_sess_number>(SSL_CTX *ctx); + +=item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx, t); + +=item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)); + +=item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess)); + +=item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)); + +=item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx); + +=item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx); + +=item int B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg); + +=item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs); + +=item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg) + +=item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str); + +=item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list); + +=item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); + +=item int B<SSL_CTX_set_ct_validation_callback>(SSL_CTX *ctx, ssl_ct_validation_cb callback, void *arg); + +=item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void)) + +=item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m); + +=item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx); + +Use the default paths to locate trusted CA certificates. There is one default +directory path and one default file path. Both are set via this call. + +=item int B<SSL_CTX_set_default_verify_dir>(SSL_CTX *ctx) + +Use the default directory path to locate trusted CA certificates. + +=item int B<SSL_CTX_set_default_verify_file>(SSL_CTX *ctx) + +Use the file path to locate trusted CA certificates. + +=item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg); + +=item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret)); + +=item void B<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)); + +=item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg); + +=item unsigned long B<SSL_CTX_clear_options>(SSL_CTX *ctx, unsigned long op); + +=item unsigned long B<SSL_CTX_get_options>(SSL_CTX *ctx); + +=item unsigned long B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op); + +=item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode); + +=item void B<SSL_CTX_set_read_ahead>(SSL_CTX *ctx, int m); + +=item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode); + +=item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth); + +=item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t); + +=item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh); + +=item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void)); + +=item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void)) + +=item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey); + +=item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len); + +=item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, const char *file, int type); + +=item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa); + +=item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len); + +=item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, const char *file, int type); + +=item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x); + +=item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d); + +=item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, const char *file, int type); + +=item X509 *B<SSL_CTX_get0_certificate>(const SSL_CTX *ctx); + +=item EVP_PKEY *B<SSL_CTX_get0_privatekey>(const SSL_CTX *ctx); + +=item void B<SSL_CTX_set_psk_client_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); + +=item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint); + +=item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); + + +=back + +=head2 Dealing with Sessions + +Here we document the various API functions which deal with the SSL/TLS +sessions defined in the B<SSL_SESSION> structures. + +=over 4 + +=item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b); + +=item void B<SSL_SESSION_free>(SSL_SESSION *ss); + +=item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s); + +=item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx); + +=item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) + +=item long B<SSL_SESSION_get_time>(const SSL_SESSION *s); + +=item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s); + +=item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a); + +=item SSL_SESSION *B<SSL_SESSION_new>(void); + +=item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x); + +=item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x); + +=item int B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a); + +=item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg); + +=item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t); + +=item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t); + +=back + +=head2 Dealing with Connections + +Here we document the various API functions which deal with the SSL/TLS +connection defined in the B<SSL> structure. + +=over 4 + +=item int B<SSL_accept>(SSL *ssl); + +=item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir); + +=item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file); + +=item int B<SSL_add_client_CA>(SSL *ssl, X509 *x); + +=item char *B<SSL_alert_desc_string>(int value); + +=item char *B<SSL_alert_desc_string_long>(int value); + +=item char *B<SSL_alert_type_string>(int value); + +=item char *B<SSL_alert_type_string_long>(int value); + +=item int B<SSL_check_private_key>(const SSL *ssl); + +=item void B<SSL_clear>(SSL *ssl); + +=item long B<SSL_clear_num_renegotiations>(SSL *ssl); + +=item int B<SSL_connect>(SSL *ssl); + +=item int B<SSL_copy_session_id>(SSL *t, const SSL *f); + +Sets the session details for B<t> to be the same as in B<f>. Returns 1 on +success or 0 on failure. + +=item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg); + +=item int B<SSL_do_handshake>(SSL *ssl); + +=item SSL *B<SSL_dup>(SSL *ssl); + +SSL_dup() allows applications to configure an SSL handle for use +in multiple SSL connections, and then duplicate it prior to initiating +each connection with the duplicated handle. +Use of SSL_dup() avoids the need to repeat the configuration of the +handles for each connection. + +For SSL_dup() to work, the connection MUST be in its initial state +and MUST NOT have not yet have started the SSL handshake. +For connections that are not in their initial state SSL_dup() just +increments an internal reference count and returns the I<same> +handle. +It may be possible to use L<SSL_clear(3)> to recycle an SSL handle +that is not in its initial state for re-use, but this is best +avoided. +Instead, save and restore the session, if desired, and construct a +fresh handle for each connection. + +=item STACK *B<SSL_dup_CA_list>(STACK *sk); + +=item void B<SSL_free>(SSL *ssl); + +=item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl); + +=item char *B<SSL_get_app_data>(SSL *ssl); + +=item X509 *B<SSL_get_certificate>(const SSL *ssl); + +=item const char *B<SSL_get_cipher>(const SSL *ssl); + +=item int B<SSL_is_dtls>(const SSL *ssl); + +=item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits); + +=item char *B<SSL_get_cipher_list>(const SSL *ssl, int n); + +=item char *B<SSL_get_cipher_name>(const SSL *ssl); + +=item char *B<SSL_get_cipher_version>(const SSL *ssl); + +=item STACK *B<SSL_get_ciphers>(const SSL *ssl); + +=item STACK *B<SSL_get_client_CA_list>(const SSL *ssl); + +=item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl); + +=item long B<SSL_get_default_timeout>(const SSL *ssl); + +=item int B<SSL_get_error>(const SSL *ssl, int i); + +=item char *B<SSL_get_ex_data>(const SSL *ssl, int idx); + +=item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void); + +=item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) + +=item int B<SSL_get_fd>(const SSL *ssl); + +=item void (*B<SSL_get_info_callback>(const SSL *ssl);)() + +=item int B<SSL_get_key_update_type>(SSL *s); + +=item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl); + +=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl); + +=item const STACK_OF(SCT) *B<SSL_get0_peer_scts>(SSL *s); + +=item EVP_PKEY *B<SSL_get_privatekey>(const SSL *ssl); + +=item int B<SSL_get_quiet_shutdown>(const SSL *ssl); + +=item BIO *B<SSL_get_rbio>(const SSL *ssl); + +=item int B<SSL_get_read_ahead>(const SSL *ssl); + +=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl); + +=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len); + +=item int B<SSL_get_shutdown>(const SSL *ssl); + +=item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl); + +=item int B<SSL_get_state>(const SSL *ssl); + +=item long B<SSL_get_time>(const SSL *ssl); + +=item long B<SSL_get_timeout>(const SSL *ssl); + +=item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int, X509_STORE_CTX *) + +=item int B<SSL_get_verify_mode>(const SSL *ssl); + +=item long B<SSL_get_verify_result>(const SSL *ssl); + +=item char *B<SSL_get_version>(const SSL *ssl); + +=item BIO *B<SSL_get_wbio>(const SSL *ssl); + +=item int B<SSL_in_accept_init>(SSL *ssl); + +=item int B<SSL_in_before>(SSL *ssl); + +=item int B<SSL_in_connect_init>(SSL *ssl); + +=item int B<SSL_in_init>(SSL *ssl); + +=item int B<SSL_is_init_finished>(SSL *ssl); + +=item int B<SSL_key_update>(SSL *s, int updatetype); + +=item STACK *B<SSL_load_client_CA_file>(const char *file); + +=item SSL *B<SSL_new>(SSL_CTX *ctx); + +=item int SSL_up_ref(SSL *s); + +=item long B<SSL_num_renegotiations>(SSL *ssl); + +=item int B<SSL_peek>(SSL *ssl, void *buf, int num); + +=item int B<SSL_pending>(const SSL *ssl); + +=item int B<SSL_read>(SSL *ssl, void *buf, int num); + +=item int B<SSL_renegotiate>(SSL *ssl); + +=item char *B<SSL_rstate_string>(SSL *ssl); + +=item char *B<SSL_rstate_string_long>(SSL *ssl); + +=item long B<SSL_session_reused>(SSL *ssl); + +=item void B<SSL_set_accept_state>(SSL *ssl); + +=item void B<SSL_set_app_data>(SSL *ssl, char *arg); + +=item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio); + +=item int B<SSL_set_cipher_list>(SSL *ssl, char *str); + +=item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list); + +=item void B<SSL_set_connect_state>(SSL *ssl); + +=item int B<SSL_set_ct_validation_callback>(SSL *ssl, ssl_ct_validation_cb callback, void *arg); + +=item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg); + +=item int B<SSL_set_fd>(SSL *ssl, int fd); + +=item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void)) + +=item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); + +=item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg); + +=item unsigned long B<SSL_clear_options>(SSL *ssl, unsigned long op); + +=item unsigned long B<SSL_get_options>(SSL *ssl); + +=item unsigned long B<SSL_set_options>(SSL *ssl, unsigned long op); + +=item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode); + +=item void B<SSL_set_read_ahead>(SSL *ssl, int yes); + +=item int B<SSL_set_rfd>(SSL *ssl, int fd); + +=item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session); + +=item void B<SSL_set_shutdown>(SSL *ssl, int mode); + +=item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth); + +=item void B<SSL_set_time>(SSL *ssl, long t); + +=item void B<SSL_set_timeout>(SSL *ssl, long t); + +=item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void)) + +=item void B<SSL_set_verify_result>(SSL *ssl, long arg); + +=item int B<SSL_set_wfd>(SSL *ssl, int fd); + +=item int B<SSL_shutdown>(SSL *ssl); + +=item OSSL_HANDSHAKE_STATE B<SSL_get_state>(const SSL *ssl); + +Returns the current handshake state. + +=item char *B<SSL_state_string>(const SSL *ssl); + +=item char *B<SSL_state_string_long>(const SSL *ssl); + +=item long B<SSL_total_renegotiations>(SSL *ssl); + +=item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey); + +=item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len); + +=item int B<SSL_use_PrivateKey_file>(SSL *ssl, const char *file, int type); + +=item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa); + +=item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len); + +=item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, const char *file, int type); + +=item int B<SSL_use_certificate>(SSL *ssl, X509 *x); + +=item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d); + +=item int B<SSL_use_certificate_file>(SSL *ssl, const char *file, int type); + +=item int B<SSL_version>(const SSL *ssl); + +=item int B<SSL_want>(const SSL *ssl); + +=item int B<SSL_want_nothing>(const SSL *ssl); + +=item int B<SSL_want_read>(const SSL *ssl); + +=item int B<SSL_want_write>(const SSL *ssl); + +=item int B<SSL_want_x509_lookup>(const SSL *ssl); + +=item int B<SSL_write>(SSL *ssl, const void *buf, int num); + +=item void B<SSL_set_psk_client_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); + +=item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint); + +=item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); + +=item const char *B<SSL_get_psk_identity_hint>(SSL *ssl); + +=item const char *B<SSL_get_psk_identity>(SSL *ssl); + +=back + +=head1 RETURN VALUES + +See the individual manual pages for details. + +=head1 SEE ALSO + +L<openssl(1)>, L<crypto(7)>, +L<CRYPTO_get_ex_new_index(3)>, +L<SSL_accept(3)>, L<SSL_clear(3)>, +L<SSL_connect(3)>, +L<SSL_CIPHER_get_name(3)>, +L<SSL_COMP_add_compression_method(3)>, +L<SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_add_session(3)>, +L<SSL_CTX_ctrl(3)>, +L<SSL_CTX_flush_sessions(3)>, +L<SSL_CTX_get_verify_mode(3)>, +L<SSL_CTX_load_verify_locations(3)> +L<SSL_CTX_new(3)>, +L<SSL_CTX_sess_number(3)>, +L<SSL_CTX_sess_set_cache_size(3)>, +L<SSL_CTX_sess_set_get_cb(3)>, +L<SSL_CTX_sessions(3)>, +L<SSL_CTX_set_cert_store(3)>, +L<SSL_CTX_set_cert_verify_callback(3)>, +L<SSL_CTX_set_cipher_list(3)>, +L<SSL_CTX_set_client_CA_list(3)>, +L<SSL_CTX_set_client_cert_cb(3)>, +L<SSL_CTX_set_default_passwd_cb(3)>, +L<SSL_CTX_set_generate_session_id(3)>, +L<SSL_CTX_set_info_callback(3)>, +L<SSL_CTX_set_max_cert_list(3)>, +L<SSL_CTX_set_mode(3)>, +L<SSL_CTX_set_msg_callback(3)>, +L<SSL_CTX_set_options(3)>, +L<SSL_CTX_set_quiet_shutdown(3)>, +L<SSL_CTX_set_read_ahead(3)>, +L<SSL_CTX_set_security_level(3)>, +L<SSL_CTX_set_session_cache_mode(3)>, +L<SSL_CTX_set_session_id_context(3)>, +L<SSL_CTX_set_ssl_version(3)>, +L<SSL_CTX_set_timeout(3)>, +L<SSL_CTX_set_tmp_dh_callback(3)>, +L<SSL_CTX_set_verify(3)>, +L<SSL_CTX_use_certificate(3)>, +L<SSL_alert_type_string(3)>, +L<SSL_do_handshake(3)>, +L<SSL_enable_ct(3)>, +L<SSL_get_SSL_CTX(3)>, +L<SSL_get_ciphers(3)>, +L<SSL_get_client_CA_list(3)>, +L<SSL_get_default_timeout(3)>, +L<SSL_get_error(3)>, +L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>, +L<SSL_get_fd(3)>, +L<SSL_get_peer_cert_chain(3)>, +L<SSL_get_rbio(3)>, +L<SSL_get_session(3)>, +L<SSL_get_verify_result(3)>, +L<SSL_get_version(3)>, +L<SSL_load_client_CA_file(3)>, +L<SSL_new(3)>, +L<SSL_pending(3)>, +L<SSL_read_ex(3)>, +L<SSL_read(3)>, +L<SSL_rstate_string(3)>, +L<SSL_session_reused(3)>, +L<SSL_set_bio(3)>, +L<SSL_set_connect_state(3)>, +L<SSL_set_fd(3)>, +L<SSL_set_session(3)>, +L<SSL_set_shutdown(3)>, +L<SSL_shutdown(3)>, +L<SSL_state_string(3)>, +L<SSL_want(3)>, +L<SSL_write_ex(3)>, +L<SSL_write(3)>, +L<SSL_SESSION_free(3)>, +L<SSL_SESSION_get_time(3)>, +L<d2i_SSL_SESSION(3)>, +L<SSL_CTX_set_psk_client_callback(3)>, +L<SSL_CTX_use_psk_identity_hint(3)>, +L<SSL_get_psk_identity(3)>, +L<DTLSv1_listen(3)> + +=head1 HISTORY + +B<SSLv2_client_method>, B<SSLv2_server_method> and B<SSLv2_method> were removed +in OpenSSL 1.1.0. + +The return type of B<SSL_copy_session_id> was changed from void to int in +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |