diff options
| author | William Joye <wjoye@cfa.harvard.edu> | 2017-05-02 16:40:01 (GMT) |
|---|---|---|
| committer | William Joye <wjoye@cfa.harvard.edu> | 2017-05-02 16:40:01 (GMT) |
| commit | 0a2b8b8e0bc2e91a9f10659b30e2e4f5b79ce692 (patch) | |
| tree | 3d0871d05cfd11f60b86829d2d93704034dad24e /openssl/doc | |
| parent | e9abe0dba896d2b0fc22301588336e89ff246ba7 (diff) | |
| download | blt-0a2b8b8e0bc2e91a9f10659b30e2e4f5b79ce692.zip blt-0a2b8b8e0bc2e91a9f10659b30e2e4f5b79ce692.tar.gz blt-0a2b8b8e0bc2e91a9f10659b30e2e4f5b79ce692.tar.bz2 | |
reinstall
Diffstat (limited to 'openssl/doc')
381 files changed, 0 insertions, 52767 deletions
diff --git a/openssl/doc/HOWTO/certificates.txt b/openssl/doc/HOWTO/certificates.txt deleted file mode 100644 index 65f8fc8..0000000 --- a/openssl/doc/HOWTO/certificates.txt +++ /dev/null @@ -1,110 +0,0 @@ -<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/doc/HOWTO/keys.txt b/openssl/doc/HOWTO/keys.txt deleted file mode 100644 index ba0314f..0000000 --- a/openssl/doc/HOWTO/keys.txt +++ /dev/null @@ -1,72 +0,0 @@ -<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. - - NOTE: if you intend to use the key together with a server - certificate, it may be a good thing to avoid protecting it - with a password, since that would mean someone would have to - type in the password every time the server needs to access - the key. - -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. - - NOTE: if you intend to use the key together with a server - certificate, it may be a good thing to avoid protecting it - with a password, since that would mean someone would have to - type in the password every time the server needs to access - the key. - --- -Richard Levitte diff --git a/openssl/doc/HOWTO/proxy_certificates.txt b/openssl/doc/HOWTO/proxy_certificates.txt deleted file mode 100644 index d78be2f..0000000 --- a/openssl/doc/HOWTO/proxy_certificates.txt +++ /dev/null @@ -1,306 +0,0 @@ - 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: - - /* 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 / 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(void) - { - static volatile int idx = -1; - if (idx < 0) - { - CRYPTO_w_lock(CRYPTO_LOCK_X509_STORE); - if (idx < 0) - { - idx = X509_STORE_CTX_get_ex_new_index(0, - "for verify callback", - NULL,NULL,NULL); - } - CRYPTO_w_unlock(CRYPTO_LOCK_X509_STORE); - } - 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 = ctx->current_cert; - - if (xs->ex_flags & EXFLAG_PROXY) - { - YOUR_RIGHTS *rights = - (YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx, - get_proxy_auth_ex_data_idx()); - 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 (!(xs->ex_flags & EXFLAG_CA)) - { - /* We have a 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()); - - /* 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 i; - int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) = ctx->verify_cb; - 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(), &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/doc/README b/openssl/doc/README deleted file mode 100644 index cc76040..0000000 --- a/openssl/doc/README +++ /dev/null @@ -1,21 +0,0 @@ - -README This file - -fingerprints.txt - PGP fingerprints of authoried release signers - -standards.txt - Pointers to standards, RFC's and IETF Drafts that are - related to OpenSSL. Incomplete. - -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/doc/apps/CA.pl.pod b/openssl/doc/apps/CA.pl.pod deleted file mode 100644 index d326101..0000000 --- a/openssl/doc/apps/CA.pl.pod +++ /dev/null @@ -1,179 +0,0 @@ - -=pod - -=head1 NAME - -CA.pl - friendlier interface for OpenSSL certificate programs - -=head1 SYNOPSIS - -B<CA.pl> -[B<-?>] -[B<-h>] -[B<-help>] -[B<-newcert>] -[B<-newreq>] -[B<-newreq-nodes>] -[B<-newca>] -[B<-xsign>] -[B<-sign>] -[B<-signreq>] -[B<-signcert>] -[B<-verify>] -[B<files>] - -=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 COMMAND 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". - -=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". - -=item B<-newreq-nodes> - -is like B<-newreq> except that the private key will not be encrypted. - -=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. - -=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. - -=item B<-sign>, B<-signreq>, 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. - - -=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. - -=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". - -=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". - -=item B<files> - -one or more optional certificate file names for use with the B<-verify> command. - -=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)|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 "openssl.cnf". - -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 ENVIRONMENT VARIABLES - -The variable B<OPENSSL_CONF> if defined allows an alternative configuration -file location to be specified, it should contain the full path to the -configuration file, not just its directory. - -=head1 SEE ALSO - -L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<req(1)|req(1)>, L<pkcs12(1)|pkcs12(1)>, -L<config(5)|config(5)> - -=cut diff --git a/openssl/doc/apps/asn1parse.pod b/openssl/doc/apps/asn1parse.pod deleted file mode 100644 index 76a765d..0000000 --- a/openssl/doc/apps/asn1parse.pod +++ /dev/null @@ -1,185 +0,0 @@ -=pod - -=head1 NAME - -asn1parse - ASN.1 parsing tool - -=head1 SYNOPSIS - -B<openssl> B<asn1parse> -[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>] - -=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<-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)|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. - -=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)|ASN1_generate_nconf(3)> - -=cut diff --git a/openssl/doc/apps/c_rehash.pod b/openssl/doc/apps/c_rehash.pod deleted file mode 100644 index ccce29e..0000000 --- a/openssl/doc/apps/c_rehash.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=for comment -Original text by James Westby, contributed under the OpenSSL license. - -=head1 NAME - -c_rehash - Create symbolic links to files named by the hash values - -=head1 SYNOPSIS - -B<c_rehash> -B<[-old]> -B<[-h]> -B<[-n]> -B<[-v]> -[ I<directory>...] - -=head1 DESCRIPTION - -B<c_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 shold be a colon-separated list of directories, -like the Unix B<PATH> variable. -If that is not set then the default directory (installation-specific -but often B</usr/local/ssl/certs>) is processed. - -In order for a directory to be processed, the user must have write -permissions on that directory, otherwise it will be skipped. -The links created are of the form C<HHHHHHHH.D>, where each B<H> -is a hexadecimal character and B<D> is a single decimal digit. -When processing a directory, B<c_rehash> will first remove all links -that have a name in that syntax. If you have links in that format -used for other purposes, they will be removed. -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. - -The program uses the B<openssl> program to compute the hashes and -fingerprints. If not found in the user's B<PATH>, then set the -B<OPENSSL> environment variable to the full pathname. -Any program can be used, it will be invoked as follows for either -a certificate or CRL: - - $OPENSSL x509 -hash -fingerprint -noout -in 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<-old> - -Use old-style hashing (MD5, as opposed to SHA-1) for generating -links for releases before 1.0.0. Note that current versions will -not use the old style. - -=item B<-h> - -Display a brief usage message. - -=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<c_rehash> only lists each directory as it is processed. - -=back - -=head1 ENVIRONMENT - -=over - -=item B<OPENSSL> - -The path to an executable to use to generate hashes and -fingerprints (see above). - -=item B<SSL_CERT_DIR> - -Colon separated list of directories to operate on. -Ignored if directories are listed on the command line. - -=back - -=head1 SEE ALSO - -L<openssl(1)|openssl(1)>, -L<crl(1)|crl(1)>. -L<x509(1)|x509(1)>. diff --git a/openssl/doc/apps/ca.pod b/openssl/doc/apps/ca.pod deleted file mode 100644 index c90e648..0000000 --- a/openssl/doc/apps/ca.pod +++ /dev/null @@ -1,696 +0,0 @@ - -=pod - -=head1 NAME - -ca - sample minimal CA application - -=head1 SYNOPSIS - -B<openssl> B<ca> -[B<-verbose>] -[B<-config filename>] -[B<-name section>] -[B<-gencrl>] -[B<-revoke file>] -[B<-status serial>] -[B<-updatedb>] -[B<-crl_reason reason>] -[B<-crl_hold instruction>] -[B<-crl_compromise time>] -[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<-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 CA OPTIONS - -=over 4 - -=item B<-config filename> - -specifies the configuration file to use. - -=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 assumed to the 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>). -Cerificate 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)|openssl(1)>. - -=item B<-verbose> - -this prints extra details about the operations being performed. - -=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. Possible values include md5, sha1 and mdc2. -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)|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<-multivalue-rdn> - -this option causes the -subj argument to be interpretedt 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<-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 practive 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)|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)|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. The message digest to use. 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. - -=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 ENVIRONMENT VARIABLES - -B<OPENSSL_CONF> reflects the location of master configuration file it can -be overridden by the B<-config> command line option. - -=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 scripts B<CA.sh> and -B<CA.pl> help 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. - -Cancelling 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 requestor -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)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>, -L<config(5)|config(5)>, L<x509v3_config(5)|x509v3_config(5)> - -=cut diff --git a/openssl/doc/apps/ciphers.pod b/openssl/doc/apps/ciphers.pod deleted file mode 100644 index 9224557..0000000 --- a/openssl/doc/apps/ciphers.pod +++ /dev/null @@ -1,645 +0,0 @@ -=pod - -=head1 NAME - -ciphers - SSL cipher display and cipher list tool. - -=head1 SYNOPSIS - -B<openssl> B<ciphers> -[B<-v>] -[B<-V>] -[B<-ssl2>] -[B<-ssl3>] -[B<-tls1>] -[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 COMMAND OPTIONS - -=over 4 - -=item B<-v> - -Verbose option. List ciphers with a complete description of -protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange, -authentication, encryption and mac algorithms used along with any key size -restrictions and whether the algorithm is classed as an "export" cipher. -Note that without the B<-v> option, ciphers may seem to appear twice -in a cipher list; this is when similar ciphers are available for -SSL v2 and for SSL v3/TLS v1. - -=item B<-V> - -Like B<-v>, but include cipher suite codes in output (hex format). - -=item B<-ssl3>, B<-tls1> - -This lists ciphers compatible with any of SSLv3, TLSv1, TLSv1.1 or TLSv1.2. - -=item B<-ssl2> - -Only include SSLv2 ciphers. - -=item B<-h>, B<-?> - -Print a brief usage message. - -=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. - -Additionally the cipher string B<@STRENGTH> can be used at any point to sort -the current cipher list in order of encryption algorithm key length. - -=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:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2>. -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 is B<ADH> and B<AECDH>. Note that this rule does not cover B<eNULL>, -which is not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary). - -=item B<ALL> - -all cipher suites except the B<eNULL> ciphers which must be explicitly enabled; -as of OpenSSL, the B<ALL> cipher suites are reasonably ordered by default - -=item B<COMPLEMENTOFALL> - -the cipher suites not enabled by B<ALL>, currently being 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 strength encryption cipher suites, currently those using 64 or 56 bit -encryption algorithms but excluding export cipher suites. -As of OpenSSL 1.0.2g, these are disabled in default builds. - -=item B<EXP>, B<EXPORT> - -Export strength encryption algorithms. Including 40 and 56 bits algorithms. -As of OpenSSL 1.0.2g, these are disabled in default builds. - -=item B<EXPORT40> - -40-bit export encryption algorithms -As of OpenSSL 1.0.2g, these are disabled in default builds. - -=item B<EXPORT56> - -56-bit export encryption algorithms. In OpenSSL 0.9.8c and later the set of -56 bit export ciphers is empty unless OpenSSL has been explicitly configured -with support for experimental ciphers. -As of OpenSSL 1.0.2g, these are disabled in default builds. - -=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 a "man in the middle" attack and so their use is normally 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<RSA> - -cipher suites using RSA key exchange. - -=item B<kDHr>, B<kDHd>, B<kDH> - -cipher suites using DH key agreement and DH certificates signed by CAs with RSA -and DSS keys or either respectively. - -=item B<kDHE>, B<kEDH> - -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<DH> - -cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH. - -=item B<kECDHr>, B<kECDHe>, B<kECDH> - -cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA -keys or either respectively. - -=item B<kECDHE>, B<kEECDH> - -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<ECDH> - -cipher suites using ECDH key exchange, including anonymous, ephemeral and -fixed ECDH. - -=item B<aRSA> - -cipher suites using RSA authentication, i.e. the certificates carry RSA keys. - -=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. - -=item B<aECDH> - -cipher suites effectively using ECDH authentication, i.e. the certificates -carry ECDH keys. - -=item B<aECDSA>, B<ECDSA> - -cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA -keys. - -=item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA> - -ciphers suites using FORTEZZA key exchange, authentication, encryption or all -FORTEZZA algorithms. Not implemented. - -=item B<TLSv1.2>, B<TLSv1>, B<SSLv3>, B<SSLv2> - -TLS v1.2, TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. Note: -there are no ciphersuites specific to TLS v1.1. - -=item B<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<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA> - -cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit -CAMELLIA. - -=item B<3DES> - -cipher suites using triple DES. - -=item B<DES> - -cipher suites using DES (not triple DES). - -=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 authenticaction -(needs an engine supporting GOST algorithms). - -=item B<aGOST01> - -cipher suites using GOST R 34.10-2001 authentication. - -=item B<aGOST94> - -cipher suites using GOST R 34.10-94 authentication (note that R 34.10-94 -standard has been expired so use GOST R 34.10-2001) - -=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> - -cipher suites using pre-shared keys (PSK). - -=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192> - -enables suite B mode 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_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5 - SSL_RSA_WITH_RC4_128_MD5 RC4-MD5 - SSL_RSA_WITH_RC4_128_SHA RC4-SHA - SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5 - SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA - SSL_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA - SSL_RSA_WITH_DES_CBC_SHA DES-CBC-SHA - SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA - - SSL_DH_DSS_WITH_DES_CBC_SHA DH-DSS-DES-CBC-SHA - SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA - SSL_DH_RSA_WITH_DES_CBC_SHA DH-RSA-DES-CBC-SHA - SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-RSA-DES-CBC3-SHA - SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA - SSL_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA - SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA - SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA - SSL_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA - SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA - - SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5 - SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 - SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA - SSL_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA - 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_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5 - TLS_RSA_WITH_RC4_128_MD5 RC4-MD5 - TLS_RSA_WITH_RC4_128_SHA RC4-SHA - TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5 - TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA - TLS_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA - TLS_RSA_WITH_DES_CBC_SHA DES-CBC-SHA - TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA - - TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented. - TLS_DH_DSS_WITH_DES_CBC_SHA Not implemented. - TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented. - TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented. - TLS_DH_RSA_WITH_DES_CBC_SHA Not implemented. - TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented. - TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA - TLS_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA - TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA - TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA - TLS_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA - TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA - - TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5 - TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 - TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA - TLS_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA - 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_RSA_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DES-CBC-SHA - TLS_RSA_EXPORT1024_WITH_RC4_56_SHA EXP1024-RC4-SHA - TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DHE-DSS-DES-CBC-SHA - TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA EXP1024-DHE-DSS-RC4-SHA - TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA - -=head2 Elliptic curve cipher suites. - - TLS_ECDH_RSA_WITH_NULL_SHA ECDH-RSA-NULL-SHA - TLS_ECDH_RSA_WITH_RC4_128_SHA ECDH-RSA-RC4-SHA - TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA ECDH-RSA-DES-CBC3-SHA - TLS_ECDH_RSA_WITH_AES_128_CBC_SHA ECDH-RSA-AES128-SHA - TLS_ECDH_RSA_WITH_AES_256_CBC_SHA ECDH-RSA-AES256-SHA - - TLS_ECDH_ECDSA_WITH_NULL_SHA ECDH-ECDSA-NULL-SHA - TLS_ECDH_ECDSA_WITH_RC4_128_SHA ECDH-ECDSA-RC4-SHA - TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA ECDH-ECDSA-DES-CBC3-SHA - TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA ECDH-ECDSA-AES128-SHA - TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA ECDH-ECDSA-AES256-SHA - - TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA - TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA - TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ECDHE-RSA-AES128-SHA - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ECDHE-RSA-AES256-SHA - - TLS_ECDHE_ECDSA_WITH_NULL_SHA ECDHE-ECDSA-NULL-SHA - TLS_ECDHE_ECDSA_WITH_RC4_128_SHA ECDHE-ECDSA-RC4-SHA - TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ECDHE-ECDSA-DES-CBC3-SHA - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE-ECDSA-AES128-SHA - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE-ECDSA-AES256-SHA - - TLS_ECDH_anon_WITH_NULL_SHA AECDH-NULL-SHA - TLS_ECDH_anon_WITH_RC4_128_SHA AECDH-RC4-SHA - TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA AECDH-DES-CBC3-SHA - TLS_ECDH_anon_WITH_AES_128_CBC_SHA AECDH-AES128-SHA - TLS_ECDH_anon_WITH_AES_256_CBC_SHA AECDH-AES256-SHA - -=head2 TLS v1.2 cipher suites - - TLS_RSA_WITH_NULL_SHA256 NULL-SHA256 - - TLS_RSA_WITH_AES_128_CBC_SHA256 AES128-SHA256 - TLS_RSA_WITH_AES_256_CBC_SHA256 AES256-SHA256 - TLS_RSA_WITH_AES_128_GCM_SHA256 AES128-GCM-SHA256 - TLS_RSA_WITH_AES_256_GCM_SHA384 AES256-GCM-SHA384 - - TLS_DH_RSA_WITH_AES_128_CBC_SHA256 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_ECDH_RSA_WITH_AES_128_CBC_SHA256 ECDH-RSA-AES128-SHA256 - TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 ECDH-RSA-AES256-SHA384 - TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 ECDH-RSA-AES128-GCM-SHA256 - TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 ECDH-RSA-AES256-GCM-SHA384 - - TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 ECDH-ECDSA-AES128-SHA256 - TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 ECDH-ECDSA-AES256-SHA384 - TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 ECDH-ECDSA-AES128-GCM-SHA256 - TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 ECDH-ECDSA-AES256-GCM-SHA384 - - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256 - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384 - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256 - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384 - - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE-ECDSA-AES128-SHA256 - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ECDHE-ECDSA-AES256-SHA384 - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE-ECDSA-AES128-GCM-SHA256 - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ECDHE-ECDSA-AES256-GCM-SHA384 - - TLS_DH_anon_WITH_AES_128_CBC_SHA256 ADH-AES128-SHA256 - TLS_DH_anon_WITH_AES_256_CBC_SHA256 ADH-AES256-SHA256 - TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256 - TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384 - -=head2 Pre shared keying (PSK) cipheruites - - TLS_PSK_WITH_RC4_128_SHA PSK-RC4-SHA - TLS_PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA - TLS_PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA - TLS_PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA - -=head2 Deprecated SSL v2.0 cipher suites. - - SSL_CK_RC4_128_WITH_MD5 RC4-MD5 - SSL_CK_RC4_128_EXPORT40_WITH_MD5 Not implemented. - SSL_CK_RC2_128_CBC_WITH_MD5 RC2-CBC-MD5 - SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 Not implemented. - SSL_CK_IDEA_128_CBC_WITH_MD5 IDEA-CBC-MD5 - SSL_CK_DES_64_CBC_WITH_MD5 Not implemented. - SSL_CK_DES_192_EDE3_CBC_WITH_MD5 DES-CBC3-MD5 - -=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 chiphers with RSA authentication but leave out ciphers without -encryption. - - openssl ciphers -v 'RSA:!COMPLEMENTOFALL' - -=head1 SEE ALSO - -L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)> - -=head1 HISTORY - -The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options -for cipherlist strings were added in OpenSSL 0.9.7. -The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/apps/cms.pod b/openssl/doc/apps/cms.pod deleted file mode 100644 index ac69804..0000000 --- a/openssl/doc/apps/cms.pod +++ /dev/null @@ -1,664 +0,0 @@ -=pod - -=head1 NAME - -cms - CMS utility - -=head1 SYNOPSIS - -B<openssl> B<cms> -[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_alt_chains>] -[B<-md digest>] -[B<-[cipher]>] -[B<-nointern>] -[B<-no_signer_cert_verify>] -[B<-nocerts>] -[B<-noattr>] -[B<-nosmimecap>] -[B<-binary>] -[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 COMMAND 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<-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<EncrytedData> 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<-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<-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 receipient 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<-EncrryptedData_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)|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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<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<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains> - -Set various certificate chain valiadition option. See the -L<B<verify>|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 wont 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 experimental 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)|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.0.2b. - -=cut diff --git a/openssl/doc/apps/config.pod b/openssl/doc/apps/config.pod deleted file mode 100644 index e125915..0000000 --- a/openssl/doc/apps/config.pod +++ /dev/null @@ -1,350 +0,0 @@ - -=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 B<getenv()> directly. - -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 - -In OpenSSL 0.9.7 and later 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 - -In OpenSSL 0.9.8 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 B<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 - - -=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 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 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)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)> - -=cut diff --git a/openssl/doc/apps/crl.pod b/openssl/doc/apps/crl.pod deleted file mode 100644 index 044a9da..0000000 --- a/openssl/doc/apps/crl.pod +++ /dev/null @@ -1,128 +0,0 @@ -=pod - -=head1 NAME - -crl - CRL utility - -=head1 SYNOPSIS - -B<openssl> B<crl> -[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 COMMAND OPTIONS - -=over 4 - -=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)|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)|crl2pkcs7(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)> - -=cut diff --git a/openssl/doc/apps/crl2pkcs7.pod b/openssl/doc/apps/crl2pkcs7.pod deleted file mode 100644 index 3797bc0..0000000 --- a/openssl/doc/apps/crl2pkcs7.pod +++ /dev/null @@ -1,91 +0,0 @@ -=pod - -=head1 NAME - -crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates. - -=head1 SYNOPSIS - -B<openssl> B<crl2pkcs7> -[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 COMMAND OPTIONS - -=over 4 - -=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)|pkcs7(1)> - -=cut diff --git a/openssl/doc/apps/dgst.pod b/openssl/doc/apps/dgst.pod deleted file mode 100644 index b27bb94..0000000 --- a/openssl/doc/apps/dgst.pod +++ /dev/null @@ -1,208 +0,0 @@ -=pod - -=head1 NAME - -dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests - -=head1 SYNOPSIS - -B<openssl> B<dgst> -[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>] -[B<-c>] -[B<-d>] -[B<-hex>] -[B<-binary>] -[B<-r>] -[B<-non-fips-allow>] -[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<-non-fips-allow>] -[B<-fips-fingerprint>] -[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. - -=head1 OPTIONS - -=over 4 - -=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<-non-fips-allow> - -Allow use of non FIPS digest when in FIPS mode. This has no effect when not in -FIPS mode. - -=item B<-out filename> - -filename to output to, or standard output by default. - -=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<-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. - -=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)|openssl(1)>. - -=item B<-verify filename> - -verify the signature using the the public key in "filename". -The output is either "Verification OK" or "Verification Failure". - -=item B<-prverify filename> - -verify the signature using the 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 8 - -=item B<key:string> - -Specifies MAC key as alphnumeric string (use if key contain printable -characters only). String length must conform to any restrictions of -the MAC algorithm for example exactly 32 chars for gost-mac. - -=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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-non-fips-allow> - -enable use of non-FIPS algorithms such as MD5 even in FIPS mode. - -=item B<-fips-fingerprint> - -compute HMAC using a specific key -for certain OpenSSL-FIPS operations. - -=item B<file...> - -file or files to digest. If no files are specified then standard input is -used. - -=back - - -=head1 EXAMPLES - -To create a hex-encoded message digest of a file: - openssl dgst -md5 -hex file.txt - -To sign a file using SHA-256 with binary file output: - openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt - -To verify a signature: - openssl dgst -sha256 -verify publickey.pem \ - -signature signature.sign \ - file.txt - - -=head1 NOTES - -The digest of choice for all new applications is SHA1. Other digests are -however still widely used. - -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. - - -=cut diff --git a/openssl/doc/apps/dhparam.pod b/openssl/doc/apps/dhparam.pod deleted file mode 100644 index 1cd4c76..0000000 --- a/openssl/doc/apps/dhparam.pod +++ /dev/null @@ -1,149 +0,0 @@ -=pod - -=head1 NAME - -dhparam - DH parameter manipulation and generation - -=head1 SYNOPSIS - -B<openssl dhparam> -[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<-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> - -check if the parameters are valid primes and generator. - -=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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item 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 B<get_dh>I<numbits>B<()> 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 and SSLeay. 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)|dsaparam(1)> - -=head1 HISTORY - -The B<dhparam> command was added in OpenSSL 0.9.5. -The B<-dsaparam> option was added in OpenSSL 0.9.6. - -=cut diff --git a/openssl/doc/apps/dsa.pod b/openssl/doc/apps/dsa.pod deleted file mode 100644 index 8bf6cc9..0000000 --- a/openssl/doc/apps/dsa.pod +++ /dev/null @@ -1,164 +0,0 @@ -=pod - -=head1 NAME - -dsa - DSA key processing - -=head1 SYNOPSIS - -B<openssl> B<dsa> -[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 COMMAND OPTIONS - -=over 4 - -=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)|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)|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)|dsaparam(1)>, L<gendsa(1)|gendsa(1)>, L<rsa(1)|rsa(1)>, -L<genrsa(1)|genrsa(1)> - -=cut diff --git a/openssl/doc/apps/dsaparam.pod b/openssl/doc/apps/dsaparam.pod deleted file mode 100644 index ba5ec4d..0000000 --- a/openssl/doc/apps/dsaparam.pod +++ /dev/null @@ -1,110 +0,0 @@ -=pod - -=head1 NAME - -dsaparam - DSA parameter manipulation and generation - -=head1 SYNOPSIS - -B<openssl dsaparam> -[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<-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 B<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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<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)|gendsa(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, -L<rsa(1)|rsa(1)> - -=cut diff --git a/openssl/doc/apps/ec.pod b/openssl/doc/apps/ec.pod deleted file mode 100644 index 5c7b45d..0000000 --- a/openssl/doc/apps/ec.pod +++ /dev/null @@ -1,190 +0,0 @@ -=pod - -=head1 NAME - -ec - EC key processing - -=head1 SYNOPSIS - -B<openssl> B<ec> -[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<-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 a OpenSSL EC private key into the -PKCS#8 private key format use the B<pkcs8> command. - -=head1 COMMAND OPTIONS - -=over 4 - -=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)|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)|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 a 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<-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)|ecparam(1)>, L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)> - -=head1 HISTORY - -The ec command was first introduced in OpenSSL 0.9.8. - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/openssl/doc/apps/ecparam.pod b/openssl/doc/apps/ecparam.pod deleted file mode 100644 index 88e9d1e..0000000 --- a/openssl/doc/apps/ecparam.pod +++ /dev/null @@ -1,179 +0,0 @@ -=pod - -=head1 NAME - -ecparam - EC parameter manipulation and generation - -=head1 SYNOPSIS - -B<openssl ecparam> -[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<-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 B<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> (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 a 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 a 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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-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)|ec(1)>, L<dsaparam(1)|dsaparam(1)> - -=head1 HISTORY - -The ecparam command was first introduced in OpenSSL 0.9.8. - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org) - -=cut diff --git a/openssl/doc/apps/enc.pod b/openssl/doc/apps/enc.pod deleted file mode 100644 index 41791ad..0000000 --- a/openssl/doc/apps/enc.pod +++ /dev/null @@ -1,333 +0,0 @@ -=pod - -=head1 NAME - -enc - symmetric cipher routines - -=head1 SYNOPSIS - -B<openssl enc -ciphername> -[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>] -[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<-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)|openssl(1)>. - -=item B<-salt> - -use a salt in the key derivation routines. This is the default. - -=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 -and SSLeay. - -=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<-nosalt> - -do not use a salt - -=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 hadrware-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 and SSLeay. - -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 versesion of OpenSSL, including -ones provided by configured engines. - -The B<enc> program does not support authenticated encryption modes -like CCM and GCM. The utility does not store or retrieve the -authentication tag. - - - base64 Base 64 - - 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. - -=cut diff --git a/openssl/doc/apps/errstr.pod b/openssl/doc/apps/errstr.pod deleted file mode 100644 index b3c6ccf..0000000 --- a/openssl/doc/apps/errstr.pod +++ /dev/null @@ -1,39 +0,0 @@ -=pod - -=head1 NAME - -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 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 SEE ALSO - -L<err(3)|err(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> - - -=cut diff --git a/openssl/doc/apps/gendsa.pod b/openssl/doc/apps/gendsa.pod deleted file mode 100644 index d9f56be..0000000 --- a/openssl/doc/apps/gendsa.pod +++ /dev/null @@ -1,72 +0,0 @@ -=pod - -=head1 NAME - -gendsa - generate a DSA private key from a set of parameters - -=head1 SYNOPSIS - -B<openssl> B<gendsa> -[B<-out filename>] -[B<-aes128>] -[B<-aes192>] -[B<-aes256>] -[B<-camellia128>] -[B<-camellia192>] -[B<-camellia256>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[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<-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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-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)|dsaparam(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, -L<rsa(1)|rsa(1)> - -=cut diff --git a/openssl/doc/apps/genpkey.pod b/openssl/doc/apps/genpkey.pod deleted file mode 100644 index 929edcd..0000000 --- a/openssl/doc/apps/genpkey.pod +++ /dev/null @@ -1,228 +0,0 @@ -=pod - -=head1 NAME - -genpkey - generate a private key - -=head1 SYNOPSIS - -B<openssl> B<genpkey> -[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<-out filename> - -the output filename. 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)|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 and 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 and 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 algorith 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 - -=over 4 - -=item B<ec_paramgen_curve:curve> - -the EC curve to use. - -=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 directiry 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 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 - - -=cut - diff --git a/openssl/doc/apps/genrsa.pod b/openssl/doc/apps/genrsa.pod deleted file mode 100644 index 3dc9870..0000000 --- a/openssl/doc/apps/genrsa.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -genrsa - generate an RSA private key - -=head1 SYNOPSIS - -B<openssl> B<genrsa> -[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<-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<-out filename> - -the output filename. 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)|openssl(1)>. - -=item B<-aes128|-aes192|-aes256|-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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-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 512. - -=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)|gendsa(1)> - -=cut - diff --git a/openssl/doc/apps/nseq.pod b/openssl/doc/apps/nseq.pod deleted file mode 100644 index 989c310..0000000 --- a/openssl/doc/apps/nseq.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -nseq - create or examine a netscape certificate sequence - -=head1 SYNOPSIS - -B<openssl> B<nseq> -[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 COMMAND OPTIONS - -=over 4 - -=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. - -=cut diff --git a/openssl/doc/apps/ocsp.pod b/openssl/doc/apps/ocsp.pod deleted file mode 100644 index 1bb7958..0000000 --- a/openssl/doc/apps/ocsp.pod +++ /dev/null @@ -1,401 +0,0 @@ -=pod - -=head1 NAME - -ocsp - Online Certificate Status Protocol utility - -=head1 SYNOPSIS - -B<openssl> B<ocsp> -[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:n>] -[B<-header name value>] -[B<-path>] -[B<-CApath dir>] -[B<-CAfile file>] -[B<-no_alt_chains>] -[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 OCSP CLIENT OPTIONS - -=over 4 - -=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<respin> 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. - -=item B<-header name value> - -If sending a request to an OCSP server, then the specified header name and -value are added to the HTTP request. Note that the B<name> and B<value> must -be specified as two separate parameters, not as a single quoted string, and -that the header name does not have the trailing colon. -Some OCSP responders require a Host header; use this flag to provide it. - -=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_alt_chains> - -See L<B<verify>|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<-md5|-sha1|-sha256|-ripemod160|...> - -this option sets digest algorithm to use for certificate identification -in the OCSP request. By default SHA-1 is used. - -=back - -=head1 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<respin> 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<respin> 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 and print it out in text form - - 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 - -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 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, write 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.0.2b. - -=cut diff --git a/openssl/doc/apps/openssl.pod b/openssl/doc/apps/openssl.pod deleted file mode 100644 index 64a160c..0000000 --- a/openssl/doc/apps/openssl.pod +++ /dev/null @@ -1,422 +0,0 @@ - -=pod - -=head1 NAME - -openssl - OpenSSL command line tool - -=head1 SYNOPSIS - -B<openssl> -I<command> -[ I<command_opts> ] -[ I<command_args> ] - -B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> | B<list-cipher-algorithms> | B<list-message-digest-algorithms> | B<list-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). - -The pseudo-commands B<list-standard-commands>, B<list-message-digest-commands>, -and B<list-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 pseudo-commands B<list-cipher-algorithms> and -B<list-message-digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as: - - from => to - -The pseudo-command B<list-public-key-algorithms> lists all supported public -key algorithms. - -The pseudo-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->I<...>B<-commands>, or B<no->I<XXX> itself.) - -=head2 STANDARD COMMANDS - -=over 10 - -=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 (loadble 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. Superceded 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<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<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 10 - -=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 10 - -=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 PASS PHRASE ARGUMENTS - -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 10 - -=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)|asn1parse(1)>, L<ca(1)|ca(1)>, L<config(5)|config(5)>, -L<crl(1)|crl(1)>, L<crl2pkcs7(1)|crl2pkcs7(1)>, L<dgst(1)|dgst(1)>, -L<dhparam(1)|dhparam(1)>, L<dsa(1)|dsa(1)>, L<dsaparam(1)|dsaparam(1)>, -L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>, L<genpkey(1)|genpkey(1)>, -L<genrsa(1)|genrsa(1)>, L<nseq(1)|nseq(1)>, L<openssl(1)|openssl(1)>, -L<passwd(1)|passwd(1)>, -L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>, -L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>, -L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>, -L<s_server(1)|s_server(1)>, L<s_time(1)|s_time(1)>, -L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>, -L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>, -L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)>, L<x509v3_config(5)|x509v3_config(5)> - -=head1 HISTORY - -The openssl(1) document appeared in OpenSSL 0.9.2. -The B<list->I<XXX>B<-commands> pseudo-commands were added in OpenSSL 0.9.3; -The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0; -the B<no->I<XXX> pseudo-commands were added in OpenSSL 0.9.5a. -For notes on the availability of other commands, see their individual -manual pages. - -=cut diff --git a/openssl/doc/apps/passwd.pod b/openssl/doc/apps/passwd.pod deleted file mode 100644 index f449825..0000000 --- a/openssl/doc/apps/passwd.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -passwd - compute password hashes - -=head1 SYNOPSIS - -B<openssl passwd> -[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<-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>. - -=cut diff --git a/openssl/doc/apps/pkcs12.pod b/openssl/doc/apps/pkcs12.pod deleted file mode 100644 index 7449848..0000000 --- a/openssl/doc/apps/pkcs12.pod +++ /dev/null @@ -1,368 +0,0 @@ - -=pod - -=head1 NAME - -pkcs12 - PKCS#12 file utility - -=head1 SYNOPSIS - -B<openssl> B<pkcs12> -[B<-export>] -[B<-chain>] -[B<-inkey filename>] -[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<-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 COMMAND 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<-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)|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)|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 filename> - -file to read private key from. If not present then a private key must be present -in the input file. - -=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)|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)|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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-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<-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. - -=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 BUGS - -Some would argue that the PKCS#12 standard is one big bug :-) - -Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation -routines. Under rare circumstances this could produce a PKCS#12 file encrypted -with an invalid key. As a result some PKCS#12 files which triggered this bug -from other implementations (MSIE or Netscape) could not be decrypted -by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could -not be decrypted by other implementations. The chances of producing such -a file are relatively small: less than 1 in 256. - -A side effect of fixing this bug is that any old invalidly encrypted PKCS#12 -files cannot no longer be parsed by the fixed version. Under such circumstances -the B<pkcs12> utility will report that the MAC is OK but fail with a decryption -error when extracting private keys. - -This problem can be resolved by extracting the private keys and certificates -from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12 -file from the keys and certificates using a newer version of OpenSSL. For example: - - old-openssl -in bad.p12 -out keycerts.pem - openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12 - -=head1 SEE ALSO - -L<pkcs8(1)|pkcs8(1)> - diff --git a/openssl/doc/apps/pkcs7.pod b/openssl/doc/apps/pkcs7.pod deleted file mode 100644 index acfb810..0000000 --- a/openssl/doc/apps/pkcs7.pod +++ /dev/null @@ -1,105 +0,0 @@ -=pod - -=head1 NAME - -pkcs7 - PKCS#7 utility - -=head1 SYNOPSIS - -B<openssl> B<pkcs7> -[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 COMMAND OPTIONS - -=over 4 - -=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)|crl2pkcs7(1)> - -=cut diff --git a/openssl/doc/apps/pkcs8.pod b/openssl/doc/apps/pkcs8.pod deleted file mode 100644 index 6901f1f..0000000 --- a/openssl/doc/apps/pkcs8.pod +++ /dev/null @@ -1,255 +0,0 @@ -=pod - -=head1 NAME - -pkcs8 - PKCS#8 format private key conversion tool - -=head1 SYNOPSIS - -B<openssl> B<pkcs8> -[B<-topk8>] -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-noiter>] -[B<-nocrypt>] -[B<-nooct>] -[B<-embed>] -[B<-nsdb>] -[B<-v2 alg>] -[B<-v2prf alg>] -[B<-v1 alg>] -[B<-engine id>] - -=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 COMMAND OPTIONS - -=over 4 - -=item B<-topk8> - -Normally a PKCS#8 private key is expected on input and a traditional format -private key will be written. With the B<-topk8> option the situation is -reversed: it reads a traditional format private key and writes a PKCS#8 -format key. - -=item B<-inform DER|PEM> - -This specifies the input format. If a PKCS#8 format key is expected on input -then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be -expected. Otherwise the B<DER> or B<PEM> format of the traditional format -private key is used. - -=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)|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)|openssl(1)>. - -=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<-nooct> - -This option generates RSA private keys in a broken format that some software -uses. Specifically the private key should be enclosed in a OCTET STRING -but some software just includes the structure itself without the -surrounding OCTET STRING. - -=item B<-embed> - -This option generates DSA keys in a broken format. The DSA parameters are -embedded inside the PrivateKey structure. In this form the OCTET STRING -contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing -the parameters and an ASN1 INTEGER containing the private key. - -=item B<-nsdb> - -This option generates DSA keys in a broken format compatible with Netscape -private key databases. The PrivateKey contains a SEQUENCE consisting of -the public and private keys respectively. - -=item B<-v2 alg> - -This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8 -private keys are encrypted with the password based encryption algorithm -called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it -was the strongest encryption algorithm supported in PKCS#5 v1.5. Using -the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any -encryption algorithm such as 168 bit triple DES or 128 bit RC2 however -not many implementations support PKCS#5 v2.0 yet. If you are just using -private keys with OpenSSL then this doesn't matter. - -The B<alg> argument is the encryption algorithm to use, valid values include -B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used. - -=item B<-v2prf alg> - -This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value -values would be B<hmacWithSHA256>. If this option isn't set then the default -for the cipher is used or B<hmacWithSHA1> if there is no default. - -=item B<-v1 alg> - -This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete -list of possible algorithms is included below. - -=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. - -=back - -=head1 NOTES - -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. - -The default encryption is only 56 bits because this is the encryption -that most current implementations of PKCS#8 will support. - -Some software may use PKCS#12 password based encryption algorithms -with PKCS#8 format private keys: these are handled automatically -but there is no option to produce them. - -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 from traditional to PKCS#5 v2.0 format using triple -DES: - - openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem - -Convert a private from traditional to PKCS#5 v2.0 format using AES with -256 bits in CBC mode and B<hmacWithSHA256> PRF: - - openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -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 -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 format to traditional format: - - openssl pkcs8 -in pk8.pem -out key.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. - -PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private -key format for OpenSSL: for compatibility several of the utilities use -the old format at present. - -=head1 SEE ALSO - -L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)> - -=cut diff --git a/openssl/doc/apps/pkey.pod b/openssl/doc/apps/pkey.pod deleted file mode 100644 index 4851223..0000000 --- a/openssl/doc/apps/pkey.pod +++ /dev/null @@ -1,135 +0,0 @@ - -=pod - -=head1 NAME - -pkey - public or private key processing tool - -=head1 SYNOPSIS - -B<openssl> B<pkey> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[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 COMMAND OPTIONS - -=over 4 - -=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)|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)|openssl(1)>. - -=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)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>, -L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)> - -=cut diff --git a/openssl/doc/apps/pkeyparam.pod b/openssl/doc/apps/pkeyparam.pod deleted file mode 100644 index 154f672..0000000 --- a/openssl/doc/apps/pkeyparam.pod +++ /dev/null @@ -1,69 +0,0 @@ - -=pod - -=head1 NAME - -pkeyparam - public key algorithm parameter processing tool - -=head1 SYNOPSIS - -B<openssl> B<pkeyparam> -[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 COMMAND OPTIONS - -=over 4 - -=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)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>, -L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)> - -=cut diff --git a/openssl/doc/apps/pkeyutl.pod b/openssl/doc/apps/pkeyutl.pod deleted file mode 100644 index 5da347c..0000000 --- a/openssl/doc/apps/pkeyutl.pod +++ /dev/null @@ -1,235 +0,0 @@ -=pod - -=head1 NAME - -pkeyutl - public key algorithm utility - -=head1 SYNOPSIS - -B<openssl> B<pkeyutl> -[B<-in file>] -[B<-out file>] -[B<-sigfile file>] -[B<-inkey file>] -[B<-keyform PEM|DER>] -[B<-passin arg>] -[B<-peerkey file>] -[B<-peerform PEM|DER>] -[B<-pubin>] -[B<-certin>] -[B<-rev>] -[B<-sign>] -[B<-verify>] -[B<-verifyrecover>] -[B<-encrypt>] -[B<-decrypt>] -[B<-derive>] -[B<-pkeyopt opt:value>] -[B<-hexdump>] -[B<-asn1parse>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<pkeyutl> command can be used to perform public key operations using -any supported algorithm. - -=head1 COMMAND OPTIONS - -=over 4 - -=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 a private key. - -=item B<-keyform PEM|DER> - -the key format PEM, DER or ENGINE. - -=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)|openssl(1)>. - - -=item B<-peerkey file> - -the peer key file, used by key derivation (agreement) operations. - -=item B<-peerform PEM|DER> - -the peer key format PEM, DER or ENGINE. - -=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<-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<-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. - -=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 supports encrypt, decrypt, sign, verify and verifyrecover -operations in general. Some padding modes only support some of these -operations however. - -=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<oeap> 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 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 - -=head1 SEE ALSO - -L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)> -L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> diff --git a/openssl/doc/apps/rand.pod b/openssl/doc/apps/rand.pod deleted file mode 100644 index d1d213e..0000000 --- a/openssl/doc/apps/rand.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -rand - generate pseudo-random bytes - -=head1 SYNOPSIS - -B<openssl rand> -[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<-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)|RAND_egd(3)>) -for seeding the random number generator. -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-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)|RAND_bytes(3)> - -=cut diff --git a/openssl/doc/apps/req.pod b/openssl/doc/apps/req.pod deleted file mode 100644 index 30653e5..0000000 --- a/openssl/doc/apps/req.pod +++ /dev/null @@ -1,680 +0,0 @@ - -=pod - -=head1 NAME - -req - PKCS#10 certificate request and certificate generating utility. - -=head1 SYNOPSIS - -B<openssl> B<req> -[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<-asn1-kludge>] -[B<-no-asn1-kludge>] -[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 COMMAND OPTIONS - -=over 4 - -=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)|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)|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<-subj arg> - -Replaces subject field of input request with specified data and outputs -modified 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<-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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-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 approriate 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 neccessary 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 with (such as -B<-md5>, B<-sha1>). 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, -this overrides the compile time filename or any specified in -the B<OPENSSL_CONF> environment variable. - -=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. - -=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>. -It is possible to use negative serial numbers but this is not recommended. - -=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)|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 discission of the B<-certopt> parameter in the L<B<x509>|x509(1)> -command. - - -=item B<-asn1-kludge> - -by default the B<req> command outputs certificate requests containing -no attributes in the correct PKCS#10 format. However certain CAs will only -accept requests containing no attributes in an invalid form: this -option produces this invalid format. - -More precisely the B<Attributes> in a PKCS#10 certificate request -are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so -if no attributes are present then they should be encoded as an -empty B<SET OF>. The invalid form does not include the empty -B<SET OF> whereas the correct form does. - -It should be noted that very few CAs still require the use of this option. - -=item B<-no-asn1-kludge> - -Reverses effect of B<-asn1-kludge> - -=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)|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. Possible values -include B<md5 sha1 mdc2>. 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)|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 - x509_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 = 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 ENVIRONMENT VARIABLES - -The variable B<OPENSSL_CONF> if defined allows an alternative configuration -file location to be specified, it will be overridden by the B<-config> command -line switch if it is present. For compatibility reasons the B<SSLEAY_CONF> -environment variable serves the same purpose but its use is discouraged. - -=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)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>, -L<x509v3_config(5)|x509v3_config(5)> - -=cut diff --git a/openssl/doc/apps/rsa.pod b/openssl/doc/apps/rsa.pod deleted file mode 100644 index 21cbf8e..0000000 --- a/openssl/doc/apps/rsa.pod +++ /dev/null @@ -1,210 +0,0 @@ - -=pod - -=head1 NAME - -rsa - RSA key processing tool - -=head1 SYNOPSIS - -B<openssl> B<rsa> -[B<-inform PEM|NET|DER>] -[B<-outform PEM|NET|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-sgckey>] -[B<-aes128>] -[B<-aes192>] -[B<-aes256>] -[B<-camellia128>] -[B<-camellia192>] -[B<-camellia256>] -[B<-des>] -[B<-des3>] -[B<-idea>] -[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 COMMAND OPTIONS - -=over 4 - -=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)|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)|openssl(1)>. - -=item B<-sgckey> - -use the modified NET algorithm used with some versions of Microsoft IIS and SGC -keys. - -=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. If you get -an error after entering the password try the B<-sgckey> 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)|pkcs8(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)> - -=cut diff --git a/openssl/doc/apps/rsautl.pod b/openssl/doc/apps/rsautl.pod deleted file mode 100644 index 1a498c2..0000000 --- a/openssl/doc/apps/rsautl.pod +++ /dev/null @@ -1,183 +0,0 @@ -=pod - -=head1 NAME - -rsautl - RSA utility - -=head1 SYNOPSIS - -B<openssl> B<rsautl> -[B<-in file>] -[B<-out file>] -[B<-inkey file>] -[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 COMMAND OPTIONS - -=over 4 - -=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<-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 -and 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 file -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)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)> diff --git a/openssl/doc/apps/s_client.pod b/openssl/doc/apps/s_client.pod deleted file mode 100644 index 29675dd..0000000 --- a/openssl/doc/apps/s_client.pod +++ /dev/null @@ -1,370 +0,0 @@ - -=pod - -=head1 NAME - -s_client - SSL/TLS client program - -=head1 SYNOPSIS - -B<openssl> B<s_client> -[B<-connect host:port>] -[B<-servername name>] -[B<-verify depth>] -[B<-verify_return_error>] -[B<-cert filename>] -[B<-certform DER|PEM>] -[B<-key filename>] -[B<-keyform DER|PEM>] -[B<-pass arg>] -[B<-CApath directory>] -[B<-CAfile filename>] -[B<-no_alt_chains>] -[B<-reconnect>] -[B<-pause>] -[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<-ssl2>] -[B<-ssl3>] -[B<-tls1>] -[B<-no_ssl2>] -[B<-no_ssl3>] -[B<-no_tls1>] -[B<-no_tls1_1>] -[B<-no_tls1_2>] -[B<-fallback_scsv>] -[B<-bugs>] -[B<-cipher cipherlist>] -[B<-serverpref>] -[B<-starttls protocol>] -[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>] - -=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 - -=over 4 - -=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<-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)|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<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains> - -Set various certificate chain valiadition option. See the -L<B<verify>|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<-pause> - -pauses 1 second between each read and write call. - -=item B<-showcerts> - -display the whole server certificate chain: normally only the server -certificate itself is displayed. - -=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<-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. - -=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. - -=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 the initial handshake uses a I<version-flexible> method which will -negotiate the highest mutually supported protocol version. - -=item B<-fallback_scsv> - -Send TLS_FALLBACK_SCSV in the ClientHello. - -=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 B<ciphers> -command for more information. - -=item B<-serverpref> - -use the server's cipher preferences; only used for SSLV2. - -=item B<-starttls protocol> - -send the protocol-specific message(s) to switch to TLS for communication. -B<protocol> is a keyword for the intended protocol. Currently, the only -supported keywords are "smtp", "pop3", "imap", and "ftp". - -=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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-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 -reciving ServerHello with a list of server supported protocols. - -=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<-ssl2>, -B<-ssl3>, B<-tls1>, B<-no_ssl2>, 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. - -Since the SSLv23 client hello cannot include compression methods or extensions -these will only be supported if its use is disabled, for example by using the -B<-no_sslv2> option. - -The B<s_client> utility is a test tool and is designed to continue the -handshake after any certificate verification errors. As a result it will -accept any certificate chain (trusted or not) sent by the peer. None test -applications should B<not> do this as it makes them vulnerable to a MITM -attack. This behaviour can be changed by with the B<-verify_return_error> -option: any verify errors are then returned aborting the handshake. - -=head1 BUGS - -Because this program has a lot of options and also because some of -the techniques used are rather old, the C source of s_client is rather -hard to read and not a model of how things should be done. A typical -SSL client program would be much simpler. - -The B<-prexit> option is a bit of a hack. We should really report -information whenever a session is renegotiated. - -=head1 SEE ALSO - -L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)> - -=head1 HISTORY - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/s_server.pod b/openssl/doc/apps/s_server.pod deleted file mode 100644 index fa17488..0000000 --- a/openssl/doc/apps/s_server.pod +++ /dev/null @@ -1,423 +0,0 @@ - -=pod - -=head1 NAME - -s_server - SSL/TLS server program - -=head1 SYNOPSIS - -B<openssl> B<s_server> -[B<-accept port>] -[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_alt_chains>] -[B<-nocert>] -[B<-cipher cipherlist>] -[B<-serverpref>] -[B<-quiet>] -[B<-no_tmp_rsa>] -[B<-ssl2>] -[B<-ssl3>] -[B<-tls1>] -[B<-no_ssl2>] -[B<-no_ssl3>] -[B<-no_tls1>] -[B<-no_dhe>] -[B<-bugs>] -[B<-hack>] -[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 - -=over 4 - -=item B<-accept port> - -the TCP port to listen on for connections. If not specified 4433 is used. - -=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)|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 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<-no_tmp_rsa> - -certain export cipher suites sometimes use a temporary RSA key, this option -disables temporary RSA key generation. - -=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<-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_alt_chains> - -See the L<B<verify>|verify(1)> manual page for details. - -=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<-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. - -=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 the initial handshake uses a I<version-flexible> method which will -negotiate the highest mutually supported protocol version. - -=item B<-bugs> - -there are several known bug in SSL and TLS implementations. Adding this -option enables various workarounds. - -=item B<-hack> - -this option enables a further workaround for some some early Netscape -SSL code (?). - -=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 out 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 -lots of 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<-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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<-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 SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. - -=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. - -Most web browsers (in particular Netscape and MSIE) only support RSA cipher -suites, so they cannot connect to servers which don't use a certificate -carrying an RSA key or a version of OpenSSL with RSA disabled. - -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 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<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)> - -=head1 HISTORY - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/s_time.pod b/openssl/doc/apps/s_time.pod deleted file mode 100644 index 9082d87..0000000 --- a/openssl/doc/apps/s_time.pod +++ /dev/null @@ -1,173 +0,0 @@ - -=pod - -=head1 NAME - -s_time - SSL/TLS performance timing program - -=head1 SYNOPSIS - -B<openssl> B<s_time> -[B<-connect host:port>] -[B<-www page>] -[B<-cert filename>] -[B<-key filename>] -[B<-CApath directory>] -[B<-CAfile filename>] -[B<-reuse>] -[B<-new>] -[B<-verify depth>] -[B<-nbio>] -[B<-time seconds>] -[B<-ssl2>] -[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<-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<-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<-ssl2>, 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, SSL v2 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)|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; others -will only support SSL v2 and may need the B<-ssl2> 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)|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)|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>, B<-ssl2>, -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)|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)|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)|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)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)> - -=cut diff --git a/openssl/doc/apps/sess_id.pod b/openssl/doc/apps/sess_id.pod deleted file mode 100644 index 9988d2c..0000000 --- a/openssl/doc/apps/sess_id.pod +++ /dev/null @@ -1,151 +0,0 @@ - -=pod - -=head1 NAME - -sess_id - SSL/TLS session handling utility - -=head1 SYNOPSIS - -B<openssl> B<sess_id> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[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. - -=over 4 - -=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> - -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 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 wont 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, SSLv3 or SSLv2. - -=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<Key-Arg> - -the key argument, this is only used in SSL v2. - -=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)|ciphers(1)>, L<s_server(1)|s_server(1)> - -=cut diff --git a/openssl/doc/apps/smime.pod b/openssl/doc/apps/smime.pod deleted file mode 100644 index 04a83ca..0000000 --- a/openssl/doc/apps/smime.pod +++ /dev/null @@ -1,450 +0,0 @@ -=pod - -=head1 NAME - -smime - S/MIME utility - -=head1 SYNOPSIS - -B<openssl> B<smime> -[B<-encrypt>] -[B<-decrypt>] -[B<-sign>] -[B<-resign>] -[B<-verify>] -[B<-pk7out>] -[B<-[cipher]>] -[B<-in file>] -[B<-no_alt_chains>] -[B<-certfile file>] -[B<-signer file>] -[B<-recip file>] -[B<-inform SMIME|PEM|DER>] -[B<-passin arg>] -[B<-inkey file>] -[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 COMMAND 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<-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<-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<-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> - -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<-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)|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)|RAND_egd(3)>). -Multiple files can be specified separated by a OS-dependent character. -The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. - -=item B<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<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains> - -Set various options of certificate chain verification. See -L<B<verify>|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 wont 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 experimental 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.0.2b. - -=cut diff --git a/openssl/doc/apps/speed.pod b/openssl/doc/apps/speed.pod deleted file mode 100644 index 1cd1998..0000000 --- a/openssl/doc/apps/speed.pod +++ /dev/null @@ -1,59 +0,0 @@ -=pod - -=head1 NAME - -speed - test library performance - -=head1 SYNOPSIS - -B<openssl speed> -[B<-engine id>] -[B<md2>] -[B<mdc2>] -[B<md5>] -[B<hmac>] -[B<sha1>] -[B<rmd160>] -[B<idea-cbc>] -[B<rc2-cbc>] -[B<rc5-cbc>] -[B<bf-cbc>] -[B<des-cbc>] -[B<des-ede3>] -[B<rc4>] -[B<rsa512>] -[B<rsa1024>] -[B<rsa2048>] -[B<rsa4096>] -[B<dsa512>] -[B<dsa1024>] -[B<dsa2048>] -[B<idea>] -[B<rc2>] -[B<des>] -[B<rsa>] -[B<blowfish>] - -=head1 DESCRIPTION - -This command is used to test the performance of cryptographic algorithms. - -=head1 OPTIONS - -=over 4 - -=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<[zero or more test algorithms]> - -If any options are given, B<speed> tests those algorithms, otherwise all of -the above are tested. - -=back - -=cut diff --git a/openssl/doc/apps/spkac.pod b/openssl/doc/apps/spkac.pod deleted file mode 100644 index 97fb80e..0000000 --- a/openssl/doc/apps/spkac.pod +++ /dev/null @@ -1,133 +0,0 @@ -=pod - -=head1 NAME - -spkac - SPKAC printing and generating utility - -=head1 SYNOPSIS - -B<openssl> B<spkac> -[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 COMMAND OPTIONS - -=over 4 - -=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)|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)|ca(1)> - -=cut diff --git a/openssl/doc/apps/ts.pod b/openssl/doc/apps/ts.pod deleted file mode 100644 index d6aa47d..0000000 --- a/openssl/doc/apps/ts.pod +++ /dev/null @@ -1,594 +0,0 @@ -=pod - -=head1 NAME - -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<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>] -[B<-policy> 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> private.pem] -[B<-chain> certs_file.pem] -[B<-policy> 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] - -=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, this option overrides the -B<OPENSSL_CONF> environment variable. Only the OID section -of the config file is used with the B<-query> command. (Optional) - -=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<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...> - -The message digest to apply to the data file, it supports all the message -digest algorithms that are supported by the openssl B<dgst> command. -The default is SHA-1. (Optional) - -=item B<-policy> 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, this option overrides the -B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE -OPTIONS> for configurable variables. (Optional) - -=item B<-section> tsa_section - -The name of the config file section conatining 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)|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> private.pem - -The signer private key of the TSA in PEM format. Overrides the -B<signer_key> 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<-policy> 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 trused CA certificates of the -client. See the similar option of L<verify(1)|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)|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) - -=back - -=head1 CONFIGURATION FILE OPTIONS - -The B<-query> and B<-reply> commands make use of a configuration file -defined by the B<OPENSSL_CONF> environment variable. See L<config(5)|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)|ca(1)> for description. (Optional) - -=item B<oid_section> - -See L<ca(1)|ca(1)> for description. (Optional) - -=item B<RANDFILE> - -See L<ca(1)|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<default_policy> - -The default policy to use when the request does not mandate any -policy. The same as the B<-policy> 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 ENVIRONMENT VARIABLES - -B<OPENSSL_CONF> contains the path of the configuration file and can be -overridden by the B<-config> command line option. - -=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 \ - -policy 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)|req(1)>, -L<ca(1)|ca(1)>, L<x509(1)|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 - -If you find any bugs or you have suggestions please write to -Zoltan Glozik <zglozik@opentsa.org>. Known issues: - -=over 4 - -=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)|procmail(1)> -and L<perl(1)|perl(1)>. HTTP server support is provided in the form of -a separate apache module. HTTP client support is provided by -L<tsget(1)|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)|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 - -=cut - -=head1 AUTHOR - -Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) - -=head1 SEE ALSO - -L<tsget(1)|tsget(1)>, L<openssl(1)|openssl(1)>, L<req(1)|req(1)>, -L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, -L<config(5)|config(5)> - -=cut diff --git a/openssl/doc/apps/tsget.pod b/openssl/doc/apps/tsget.pod deleted file mode 100644 index 56db985..0000000 --- a/openssl/doc/apps/tsget.pod +++ /dev/null @@ -1,194 +0,0 @@ -=pod - -=head1 NAME - -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 AUTHOR - -Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org) - -=head1 SEE ALSO - -L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>, -B<RFC 3161> - -=cut diff --git a/openssl/doc/apps/verify.pod b/openssl/doc/apps/verify.pod deleted file mode 100644 index b376732..0000000 --- a/openssl/doc/apps/verify.pod +++ /dev/null @@ -1,457 +0,0 @@ -=pod - -=head1 NAME - -verify - Utility to verify certificates. - -=head1 SYNOPSIS - -B<openssl> B<verify> -[B<-CApath directory>] -[B<-CAfile file>] -[B<-purpose purpose>] -[B<-policy arg>] -[B<-ignore_critical>] -[B<-attime timestamp>] -[B<-check_ss_sig>] -[B<-crlfile file>] -[B<-crl_download>] -[B<-crl_check>] -[B<-crl_check_all>] -[B<-policy_check>] -[B<-explicit_policy>] -[B<-inhibit_any>] -[B<-inhibit_map>] -[B<-x509_strict>] -[B<-extended_crl>] -[B<-use_deltas>] -[B<-policy_print>] -[B<-no_alt_chains>] -[B<-allow_proxy_certs>] -[B<-untrusted file>] -[B<-help>] -[B<-issuer_checks>] -[B<-trusted file>] -[B<-verbose>] -[B<->] -[certificates] - - -=head1 DESCRIPTION - -The B<verify> command verifies certificate chains. - -=head1 COMMAND OPTIONS - -=over 4 - -=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<-CAfile file> -A file of trusted certificates. The file should contain multiple certificates -in PEM format concatenated together. - -=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> - -File containing one or more CRL's (in PEM format) to load. - -=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<-untrusted file> - -A file of untrusted certificates. The file should contain multiple certificates -in PEM format concatenated together. - -=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<-help> - -Print out a usage message. - -=item B<-verbose> - -Print extra information about the operations being performed. - -=item B<-issuer_checks> - -Print out diagnostics relating to searches for the issuer certificate of the -current certificate. This shows why each candidate issuer certificate was -rejected. The presence of rejection messages does not itself imply that -anything is wrong; during the normal verification process, several -rejections may take place. - -=item B<-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<-explicit_policy> - -Set policy variable require-explicit-policy (see RFC5280). - -=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_alt_chains> - -When building a certificate chain, if the first certificate chain found is not -trusted, then OpenSSL will continue to check to see if an alternative chain can -be found that is trusted. With this option that behaviour is suppressed so that -only the first chain found is ever used. Using this option will force the -behaviour to match that of previous OpenSSL versions. - -=item B<-allow_proxy_certs> - -Allow the verification of proxy certificates. - -=item B<-trusted file> - -A file of additional trusted certificates. The file should contain multiple -certificates in PEM format concatenated together. - -=item B<-policy_print> - -Print out diagnostics related to policy processing. - -=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<-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<-x509_strict> - -For strict X.509 compliance, disable non-compliant workarounds for broken -certificates. - -=item B<-extended_crl> - -Enable extended CRL features such as indirect CRLs and alternate CRL -signing keys. - -=item B<-use_deltas> - -Enable support for delta CRLs. - -=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<-> - -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. In versions of OpenSSL before 0.9.5a the first certificate whose -subject name matched the issuer of the current certificate was assumed to be -the issuers certificate. In OpenSSL 0.9.6 and later 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 SSLeay and 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. - -An exhaustive 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<0 X509_V_OK: ok> - -the operation was successful. - -=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> - -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<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> - -the CRL of a certificate could not be found. - -=item B<4 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<5 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<6 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<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> - -the signature of the certificate is invalid. - -=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> - -the signature of the certificate is invalid. - -=item B<9 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<10 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<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> - -the CRL is not yet valid. - -=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> - -the CRL has expired. - -=item B<13 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<14 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<15 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<16 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<17 X509_V_ERR_OUT_OF_MEM: out of memory> - -an error occurred trying to allocate memory. This should never happen. - -=item B<18 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<19 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<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> - -the issuer certificate could not be found: this occurs if the issuer -certificate of an untrusted certificate cannot be found. - -=item B<21 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<22 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<23 X509_V_ERR_CERT_REVOKED: certificate revoked> - -the certificate has been revoked. - -=item B<24 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<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> - -the basicConstraints pathlength parameter has been exceeded. - -=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> - -the supplied certificate cannot be used for the specified purpose. - -=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> - -the root CA is not marked as trusted for the specified purpose. - -=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected> - -the root CA is marked to reject the specified purpose. - -=item B<29 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. Only displayed when -the B<-issuer_checks> option is set. - -=item B<30 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. Only displayed when the B<-issuer_checks> option is set. - -=item B<31 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. Only displayed when the B<-issuer_checks> option is set. - -=item B<32 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. - -=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> - -an application specific error. Unused. - -=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<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes. - -=head1 SEE ALSO - -L<x509(1)|x509(1)> - -=head1 HISTORY - -The -no_alt_chains options was first added to OpenSSL 1.0.2b. - -=cut diff --git a/openssl/doc/apps/version.pod b/openssl/doc/apps/version.pod deleted file mode 100644 index 58f543b..0000000 --- a/openssl/doc/apps/version.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -version - print OpenSSL version information - -=head1 SYNOPSIS - -B<openssl version> -[B<-a>] -[B<-v>] -[B<-b>] -[B<-o>] -[B<-f>] -[B<-p>] -[B<-d>] - -=head1 DESCRIPTION - -This command is used to print out version information about OpenSSL. - -=head1 OPTIONS - -=over 4 - -=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. - -=back - -=head1 NOTES - -The output of B<openssl version -a> would typically be used when sending -in a bug report. - -=head1 HISTORY - -The B<-d> option was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/apps/x509.pod b/openssl/doc/apps/x509.pod deleted file mode 100644 index 1479a74..0000000 --- a/openssl/doc/apps/x509.pod +++ /dev/null @@ -1,890 +0,0 @@ - -=pod - -=head1 NAME - -x509 - Certificate display and signing utility - -=head1 SYNOPSIS - -B<openssl> B<x509> -[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<-md2|-md5|-sha1|-mdc2>] -[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<-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<-md2|-md5|-sha1|-mdc2> - -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. If not -specified then SHA1 is used. If the key being used to sign with is a DSA key -then this option has no effect: SHA1 is always used with DSA keys. - -=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 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> - -prints out the digest of the DER encoded version of the whole certificate -(see digest options). - -=item B<-C> - -this outputs the certificate in the form of a C source file. - -=back - -=head2 TRUST SETTINGS - -Please note these options are currently experimental and may well change. - -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) and B<emailProtection> (S/MIME email) are used. -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. - -If the input is a certificate request then a self signed certificate -is created using the supplied private key using the subject name in -the request. - -=item B<-passin arg> - -the key password source. For more information about the format of B<arg> -see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. - -=item B<-clrext> - -delete any extensions from a certificate. This option is used when a -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>). Negative -serial numbers can also be specified but their use is not recommended. - -=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. Normally if the B<-CA> option is specified -and the serial number file does not exist it is an error. - -=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)|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. This is equivalent to specifying no name options at all. - -=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. - -=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_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 MD5 fingerprint: - - openssl x509 -in cert.pem -noout -fingerprint - -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<-fingerprint> option takes the digest of the DER encoded certificate. -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. - -The Netscape fingerprint uses MD5 whereas MSIE uses SHA1. - -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. - -The code to implement the verify behaviour described in the B<TRUST SETTINGS> -is currently being developed. It thus describes the intended behaviour rather -than the current behaviour. It is hoped that it will represent reality in -OpenSSL 0.9.5 and later. - -=head1 SEE ALSO - -L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, -L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>, -L<x509v3_config(5)|x509v3_config(5)> - -=head1 HISTORY - -Before OpenSSL 0.9.8, the default digest for RSA keys was MD5. - -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. - -=cut diff --git a/openssl/doc/apps/x509v3_config.pod b/openssl/doc/apps/x509v3_config.pod deleted file mode 100644 index fb5f79c..0000000 --- a/openssl/doc/apps/x509v3_config.pod +++ /dev/null @@ -1,529 +0,0 @@ -=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 supporte 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 - msCodeInd Microsoft Individual Code Signing (authenticode) - msCodeCom Microsoft Commercial Code Signing (authenticode) - msCTLSign Microsoft Trust List Signing - msSGC Microsoft Server Gated Crypto - msEFS Microsoft Encrypted File System - nsSGC Netscape Server Gated Crypto - -Examples: - - extendedKeyUsage=critical,codeSigning,1.2.3.4 - extendedKeyUsage=nsSGC,msSGC - - -=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 and 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)|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 IA5Strring 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 intger -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 - - -=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)|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 HISTORY - -The X509v3 extension code was first added to OpenSSL 0.9.2. - -Policy mappings, inhibit any policy and name constraints support was added in -OpenSSL 0.9.8 - -The B<directoryName> and B<otherName> option as well as the B<ASN1> option -for arbitrary extensions was added in OpenSSL 0.9.8 - -=head1 SEE ALSO - -L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>, -L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> - - -=cut diff --git a/openssl/doc/c-indentation.el b/openssl/doc/c-indentation.el deleted file mode 100644 index 90861d3..0000000 --- a/openssl/doc/c-indentation.el +++ /dev/null @@ -1,45 +0,0 @@ -; This Emacs Lisp file defines a C indentation style that closely -; follows most aspects of the one that is used throughout SSLeay, -; and hence in 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 releaes of Emacs 19). -; -; Copy the definition in your .emacs file or use M-x eval-buffer. -; 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. -; -; Apparently statement blocks that are not introduced by a statement -; such as "if" and that are not the body of a function cannot -; be handled too well by CC mode with this indentation style, -; so you have to indent them manually (you can use C-q tab). -; -; For suggesting improvements, please send e-mail to bodo@openssl.org. - -(c-add-style "eay" - '((c-basic-offset . 8) - (indent-tabs-mode . t) - (c-comment-only-line-offset . 0) - (c-hanging-braces-alist) - (c-offsets-alist . ((defun-open . +) - (defun-block-intro . 0) - (class-open . +) - (class-close . +) - (block-open . 0) - (block-close . 0) - (substatement-open . +) - (statement . 0) - (statement-block-intro . 0) - (statement-case-open . +) - (statement-case-intro . +) - (case-label . -) - (label . -) - (arglist-cont-nonempty . +) - (topmost-intro . -) - (brace-list-close . 0) - (brace-list-intro . 0) - (brace-list-open . +) - )))) - diff --git a/openssl/doc/crypto/ASN1_OBJECT_new.pod b/openssl/doc/crypto/ASN1_OBJECT_new.pod deleted file mode 100644 index 9bae40f..0000000 --- a/openssl/doc/crypto/ASN1_OBJECT_new.pod +++ /dev/null @@ -1,45 +0,0 @@ -=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 a ASN1_OBJECT structure. - -ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>. - -=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)|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)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)> - -=head1 HISTORY - -ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/ASN1_STRING_length.pod b/openssl/doc/crypto/ASN1_STRING_length.pod deleted file mode 100644 index f651e4f..0000000 --- a/openssl/doc/crypto/ASN1_STRING_length.pod +++ /dev/null @@ -1,83 +0,0 @@ -=pod - -=head1 NAME - -ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, -ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 - -ASN1_STRING utility functions - -=head1 SYNOPSIS - - #include <openssl/asn1.h> - - int ASN1_STRING_length(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(ASN1_STRING *x); - - int ASN1_STRING_to_UTF8(unsigned char **out, 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_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_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 free 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 typedefed -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 and IA5String the data will be ASCII, for a BMPString two bytes per -character in big endian format, UTF8String 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 RETURN VALUES - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -=cut diff --git a/openssl/doc/crypto/ASN1_STRING_new.pod b/openssl/doc/crypto/ASN1_STRING_new.pod deleted file mode 100644 index 8ac2a03..0000000 --- a/openssl/doc/crypto/ASN1_STRING_new.pod +++ /dev/null @@ -1,46 +0,0 @@ -=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>. - -=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)|ERR_get_error(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/ASN1_STRING_print_ex.pod b/openssl/doc/crypto/ASN1_STRING_print_ex.pod deleted file mode 100644 index 19c82ff..0000000 --- a/openssl/doc/crypto/ASN1_STRING_print_ex.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -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, ASN1_STRING *str, unsigned long flags); - int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags); - int ASN1_STRING_print(BIO *out, ASN1_STRING *str); - - -=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 '.'. - -=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)|X509_NAME_print_ex(3)>, -L<ASN1_tag2str(3)|ASN1_tag2str(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/ASN1_TIME_set.pod b/openssl/doc/crypto/ASN1_TIME_set.pod deleted file mode 100644 index ae2b53d..0000000 --- a/openssl/doc/crypto/ASN1_TIME_set.pod +++ /dev/null @@ -1,129 +0,0 @@ -=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 sucess and 0 for failure. It can fail if the -pass ASN1_TIME structure has invalid syntax for example. - -=cut diff --git a/openssl/doc/crypto/ASN1_generate_nconf.pod b/openssl/doc/crypto/ASN1_generate_nconf.pod deleted file mode 100644 index bfa0a04..0000000 --- a/openssl/doc/crypto/ASN1_generate_nconf.pod +++ /dev/null @@ -1,265 +0,0 @@ -=pod - -=head1 NAME - -ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions - -=head1 SYNOPSIS - - #include <openssl/asn1.h> - - ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf); - ASN1_TYPE *ASN1_generate_v3(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 wherease 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 2 - -=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 2 - -=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 2 - -=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 consiting 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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/BIO_ctrl.pod b/openssl/doc/crypto/BIO_ctrl.pod deleted file mode 100644 index 722e8b8..0000000 --- a/openssl/doc/crypto/BIO_ctrl.pod +++ /dev/null @@ -1,128 +0,0 @@ -=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 control operations - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg); - long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long)); - 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); - - typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3); - -=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(). -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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_f_base64.pod b/openssl/doc/crypto/BIO_f_base64.pod deleted file mode 100644 index d1d7bf0..0000000 --- a/openssl/doc/crypto/BIO_f_base64.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_base64 - base64 BIO filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/evp.h> - - 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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_f_buffer.pod b/openssl/doc/crypto/BIO_f_buffer.pod deleted file mode 100644 index c0dccf1..0000000 --- a/openssl/doc/crypto/BIO_f_buffer.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_buffer - buffering BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_f_buffer(void); - - #define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL) - #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0) - #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1) - #define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL) - #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf) - -=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 - -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)|BIO(3)>, -L<BIO_reset(3)|BIO_reset(3)>, -L<BIO_flush(3)|BIO_flush(3)>, -L<BIO_pop(3)|BIO_pop(3)>, -L<BIO_ctrl(3)|BIO_ctrl(3)>, -L<BIO_int_ctrl(3)|BIO_ctrl(3)> diff --git a/openssl/doc/crypto/BIO_f_cipher.pod b/openssl/doc/crypto/BIO_f_cipher.pod deleted file mode 100644 index 02439ce..0000000 --- a/openssl/doc/crypto/BIO_f_cipher.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/evp.h> - - 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 signalled 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 EXAMPLES - -TBA - -=head1 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_f_md.pod b/openssl/doc/crypto/BIO_f_md.pod deleted file mode 100644 index 2cc41f8..0000000 --- a/openssl/doc/crypto/BIO_f_md.pod +++ /dev/null @@ -1,144 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/evp.h> - - 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. - -Before OpenSSL 1.0.0 the call to BIO_get_md_ctx() would only work if the BIO -had been initialized for example by calling BIO_set_md() ). In OpenSSL -1.0.0 and later the context is always returned and the BIO is state is set -to initialized. 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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_f_null.pod b/openssl/doc/crypto/BIO_f_null.pod deleted file mode 100644 index b057c18..0000000 --- a/openssl/doc/crypto/BIO_f_null.pod +++ /dev/null @@ -1,32 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_null - null filter - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_f_ssl.pod b/openssl/doc/crypto/BIO_f_ssl.pod deleted file mode 100644 index a9f23f1..0000000 --- a/openssl/doc/crypto/BIO_f_ssl.pod +++ /dev/null @@ -1,322 +0,0 @@ -=pod - -=head1 NAME - -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 - -=head1 SYNOPSIS - - #include <openssl/bio.h> - #include <openssl/ssl.h> - - BIO_METHOD *BIO_f_ssl(void); - - #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) - #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) - #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) - #define BIO_set_ssl_renegotiate_bytes(b,num) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); - #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); - #define BIO_get_num_renegotiates(b) \ - BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); - - 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); - - #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) - -=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. - -In OpenSSL 0.9.6 and later 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. - -=head1 RETURN VALUES - -TBA - -=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_s_connect(3)>. - - BIO *sbio, *out; - int len; - char tmpbuf[1024]; - SSL_CTX *ctx; - SSL *ssl; - - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* We would seed the PRNG here if the platform didn't - * do it automatically - */ - - ctx = SSL_CTX_new(SSLv23_client_method()); - - /* We'd normally set some stuff like the verify paths and - * mode here because as things stand this will connect to - * any server whose certificate is signed by any CA. - */ - - sbio = BIO_new_ssl_connect(ctx); - - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ - } - - /* Don't want any retries */ - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* We might want to do other things with ssl here */ - - BIO_set_conn_hostname(sbio, "localhost: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); - /* whatever ... */ - } - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error establishing SSL connection\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - /* 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; - - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* Might seed PRNG here */ - - ctx = SSL_CTX_new(SSLv23_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); - return 0; - } - - /* Might do other things here like setting verify locations and - * DH and/or RSA temporary key callbacks - */ - - /* New SSL BIO setup as server */ - sbio=BIO_new_ssl(ctx,0); - - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ - } - - /* Don't want any retries */ - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* Create the buffering BIO */ - - bbio = BIO_new(BIO_f_buffer()); - - /* Add to chain */ - 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); - return 0; - } - - /* Now wait for incoming connection */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error in connection\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* 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); - return 0; - } - - 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"); - - /* Since there is a buffering BIO present we had better flush it */ - 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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_find_type.pod b/openssl/doc/crypto/BIO_find_type.pod deleted file mode 100644 index 2595200..0000000 --- a/openssl/doc/crypto/BIO_find_type.pod +++ /dev/null @@ -1,98 +0,0 @@ -=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); - - #define BIO_method_type(b) ((b)->method->type) - - #define BIO_TYPE_NONE 0 - #define BIO_TYPE_MEM (1|0x0400) - #define BIO_TYPE_FILE (2|0x0400) - - #define BIO_TYPE_FD (4|0x0400|0x0100) - #define BIO_TYPE_SOCKET (5|0x0400|0x0100) - #define BIO_TYPE_NULL (6|0x0400) - #define BIO_TYPE_SSL (7|0x0200) - #define BIO_TYPE_MD (8|0x0200) - #define BIO_TYPE_BUFFER (9|0x0200) - #define BIO_TYPE_CIPHER (10|0x0200) - #define BIO_TYPE_BASE64 (11|0x0200) - #define BIO_TYPE_CONNECT (12|0x0400|0x0100) - #define BIO_TYPE_ACCEPT (13|0x0400|0x0100) - #define BIO_TYPE_PROXY_CLIENT (14|0x0200) - #define BIO_TYPE_PROXY_SERVER (15|0x0200) - #define BIO_TYPE_NBIO_TEST (16|0x0200) - #define BIO_TYPE_NULL_FILTER (17|0x0200) - #define BIO_TYPE_BER (18|0x0200) - #define BIO_TYPE_BIO (19|0x0400) - - #define BIO_TYPE_DESCRIPTOR 0x0100 - #define BIO_TYPE_FILTER 0x0200 - #define BIO_TYPE_SOURCE_SINK 0x0400 - -=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 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. - -Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations. - -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 NOTES - -BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO -chain or find multiple matches using BIO_find_type(). Previous versions had to -use: - - next = bio->next_bio; - -=head1 BUGS - -BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a -NULL pointer for the B<b> argument. - -=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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_new.pod b/openssl/doc/crypto/BIO_new.pod deleted file mode 100644 index 2a245fc..0000000 --- a/openssl/doc/crypto/BIO_new.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO * BIO_new(BIO_METHOD *type); - int BIO_set(BIO *a,BIO_METHOD *type); - 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_set() sets the method of an already existing BIO. - -BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO -but it does not return a value. 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. - -=head1 RETURN VALUES - -BIO_new() returns a newly created BIO or NULL if the call fails. - -BIO_set(), BIO_free() return 1 for success and 0 for failure. - -BIO_free_all() and BIO_vfree() do not return values. - -=head1 NOTES - -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 - -TBA diff --git a/openssl/doc/crypto/BIO_new_CMS.pod b/openssl/doc/crypto/BIO_new_CMS.pod deleted file mode 100644 index 9e3a4b7..0000000 --- a/openssl/doc/crypto/BIO_new_CMS.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_encrypt(3)|CMS_encrypt(3)> - -=head1 HISTORY - -BIO_new_CMS() was added to OpenSSL 1.0.0 - -=cut diff --git a/openssl/doc/crypto/BIO_push.pod b/openssl/doc/crypto/BIO_push.pod deleted file mode 100644 index 8a2657c..0000000 --- a/openssl/doc/crypto/BIO_push.pod +++ /dev/null @@ -1,69 +0,0 @@ -=pod - -=head1 NAME - -BIO_push, BIO_pop - 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); - -=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. - -=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 - -TBA diff --git a/openssl/doc/crypto/BIO_read.pod b/openssl/doc/crypto/BIO_read.pod deleted file mode 100644 index 2c177f0..0000000 --- a/openssl/doc/crypto/BIO_read.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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>. 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. - -BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. - -BIO_puts() attempts to write a null 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. - -=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)|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)|BIO_f_buffer(3)> -to the chain. - -=head1 SEE ALSO - -L<BIO_should_retry(3)|BIO_should_retry(3)> - -TBA diff --git a/openssl/doc/crypto/BIO_s_accept.pod b/openssl/doc/crypto/BIO_s_accept.pod deleted file mode 100644 index 560c112..0000000 --- a/openssl/doc/crypto/BIO_s_accept.pod +++ /dev/null @@ -1,195 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_accept, BIO_set_accept_port, 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> - - BIO_METHOD *BIO_s_accept(void); - - long BIO_set_accept_port(BIO *b, char *name); - 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, long dummy); - - #define BIO_BIND_NORMAL 0 - #define BIO_BIND_REUSEADDR_IF_UNUSED 1 - #define BIO_BIND_REUSEADDR 2 - - 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 a 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_s_fd(3)> - -BIO_set_accept_port() uses the string B<name> to set the accept -port. The port is represented as a string of the form "host:port", -where "host" is the interface to use and "port" is the port. -The host can be can be "*" which is interpreted as meaning -any interface; "port" has the same syntax -as the port specified in BIO_set_conn_port() for connect BIOs, -that is it can be a numerical port string or a string to lookup -using getservbyname() and a string table. - -BIO_new_accept() combines BIO_new() and BIO_set_accept_port() 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 BIO_BIND_NORMAL (the default) is set -then another socket cannot be bound to the same port. If -BIO_BIND_REUSEADDR is set then other sockets can bind to the -same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and -attempt is first made to use BIO_BIN_NORMAL, if this fails -and the port is not in use then a second attempt is made -using BIO_BIND_REUSEADDR. - -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_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 - -TBA - -=head1 EXAMPLE - -This example accepts two connections on port 4444, sends messages -down each and finally closes both down. - - BIO *abio, *cbio, *cbio2; - ERR_load_crypto_strings(); - abio = BIO_new_accept("4444"); - - /* First call to BIO_accept() sets up accept BIO */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error setting up accept\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - - /* Wait for incoming connection */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); - } - 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(0); - } - 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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_s_bio.pod b/openssl/doc/crypto/BIO_s_bio.pod deleted file mode 100644 index 9fe88b2..0000000 --- a/openssl/doc/crypto/BIO_s_bio.pod +++ /dev/null @@ -1,185 +0,0 @@ -=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> - - BIO_METHOD *BIO_s_bio(void); - - #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) - #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) - - #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) - - #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) - #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) - - int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); - - #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) - size_t BIO_ctrl_get_write_guarantee(BIO *b); - - #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) - 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. - -=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(); - ... - - application | TLS-engine - | | - +----------> SSL_operations() - | /\ || - | || \/ - | BIO-pair (internal_bio) - +----------< BIO-pair (network_bio) - | | - 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 transfered 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 a 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)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)> - -=cut diff --git a/openssl/doc/crypto/BIO_s_connect.pod b/openssl/doc/crypto/BIO_s_connect.pod deleted file mode 100644 index 345a468..0000000 --- a/openssl/doc/crypto/BIO_s_connect.pod +++ /dev/null @@ -1,192 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_connect, BIO_new_connect, 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, BIO_do_connect - connect BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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_ip(BIO *b, char *ip); - long BIO_set_conn_int_port(BIO *b, char *port); - char *BIO_get_conn_hostname(BIO *b); - char *BIO_get_conn_port(BIO *b); - char *BIO_get_conn_ip(BIO *b); - long BIO_get_conn_int_port(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. The hostname can also include the -port in the form hostname:port . It is also acceptable to use the -form "hostname/any/other/path" or "hostname:port/any/other/path". - -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. Currently the -list is http, telnet, socks, https, ssl, ftp, gopher and wais. - -BIO_set_conn_ip() sets the IP address to B<ip> using binary form, -that is four bytes specifying the IP address in big-endian form. - -BIO_set_conn_int_port() sets the port using B<port>. B<port> should -be of type (int *). - -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. - -BIO_get_conn_ip() returns the IP address in binary form. - -BIO_get_conn_int_port() returns the port as an int. - -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]; - ERR_load_crypto_strings(); - 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); - /* whatever ... */ - } - 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 - -TBA diff --git a/openssl/doc/crypto/BIO_s_fd.pod b/openssl/doc/crypto/BIO_s_fd.pod deleted file mode 100644 index b1de1d1..0000000 --- a/openssl/doc/crypto/BIO_s_fd.pod +++ /dev/null @@ -1,89 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD * BIO_s_fd(void); - - #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) - #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)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 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 -using lseek(fd, 0, 0). - -BIO_seek() sets the file pointer to position B<ofs> from start of file -using lseek(fd, ofs, 0). - -BIO_tell() returns the current file position by calling 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. If B<c> is not NULL it should be of type -(int *). - -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)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)> -manual pages. - -File descriptor BIOs should not be used for socket I/O. Use socket BIOs -instead. - -=head1 RETURN VALUES - -BIO_s_fd() returns the file descriptor BIO method. - -BIO_reset() returns zero for success and -1 if an error occurred. -BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() -behaviour. - -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)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> diff --git a/openssl/doc/crypto/BIO_s_file.pod b/openssl/doc/crypto/BIO_s_file.pod deleted file mode 100644 index 188aea3..0000000 --- a/openssl/doc/crypto/BIO_s_file.pod +++ /dev/null @@ -1,148 +0,0 @@ -=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> - - 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)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>, -L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> diff --git a/openssl/doc/crypto/BIO_s_mem.pod b/openssl/doc/crypto/BIO_s_mem.pod deleted file mode 100644 index 9f23964..0000000 --- a/openssl/doc/crypto/BIO_s_mem.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - -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> - - BIO_METHOD * BIO_s_mem(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. - -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. On a -read only BIO it restores the BIO to its original state and the read only -data can be read again. - -BIO_eof() is true if no data is in the BIO. - -BIO_ctrl_pending() returns the number of bytes currently stored. - -BIO_set_mem_eof_return() sets the behaviour of memory BIO B<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. - -=head1 BUGS - -There should be an option to set the maximum size of a memory BIO. - -There should be a way to "rewind" a read write BIO without destroying -its contents. - -The copying operation should not occur after every small read of a large BIO -to improve efficiency. - -=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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_s_null.pod b/openssl/doc/crypto/BIO_s_null.pod deleted file mode 100644 index e5514f7..0000000 --- a/openssl/doc/crypto/BIO_s_null.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_null - null data sink - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - 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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_s_socket.pod b/openssl/doc/crypto/BIO_s_socket.pod deleted file mode 100644 index 1c8d3a9..0000000 --- a/openssl/doc/crypto/BIO_s_socket.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -BIO_s_socket, BIO_new_socket - socket BIO - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - BIO_METHOD *BIO_s_socket(void); - - long BIO_set_fd(BIO *b, int fd, long close_flag); - long BIO_get_fd(BIO *b, int *c); - - 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_set_fd() sets the socket of BIO B<b> to B<fd> and the close -flag to B<close_flag>. - -BIO_get_fd() places the 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_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. - -BIO_set_fd() and BIO_get_fd() are macros. - -=head1 RETURN VALUES - -BIO_s_socket() returns the socket BIO method. - -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the socket or -1 if the BIO has not been -initialized. - -BIO_new_socket() returns the newly allocated BIO or NULL is an error -occurred. - -=head1 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_set_callback.pod b/openssl/doc/crypto/BIO_set_callback.pod deleted file mode 100644 index 4759556..0000000 --- a/openssl/doc/crypto/BIO_set_callback.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - -BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, -BIO_debug_callback - BIO callback functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - #define BIO_set_callback(b,cb) ((b)->callback=(cb)) - #define BIO_get_callback(b) ((b)->callback) - #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) - #define BIO_get_callback_arg(b) ((b)->cb_arg) - - long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, - long argl,long ret); - - typedef long (*callback)(BIO *b, int oper, const char *argp, - int argi, long argl, long retvalue); - -=head1 DESCRIPTION - -BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, -they are both macros. 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_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 if is interpreted as a BIO to send the information -to, otherwise stderr is used. - -callback() is the callback function itself. The meaning of each -argument is described below. - -The BIO the callback is attached to is passed in B<b>. - -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. - -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. - -B<retvalue> 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 retvalue, if -the return value is not positive it will be immediately returned to -the application and the BIO operation will not be performed. - -The callback should normally simply return B<retvalue> when it has -finished processing, unless if specifically wishes to modify the -value returned to the application. - -=head1 CALLBACK OPERATIONS - -=over 4 - -=item B<BIO_free(b)> - -callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the -free operation. - -=item B<BIO_read(b, out, outl)> - -callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before -the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) -after. - -=item B<BIO_write(b, in, inl)> - -callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before -the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) -after. - -=item B<BIO_gets(b, out, outl)> - -callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before -the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) -after. - -=item B<BIO_puts(b, in)> - -callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before -the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) -after. - -=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> - -callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and -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 SEE ALSO - -TBA diff --git a/openssl/doc/crypto/BIO_should_retry.pod b/openssl/doc/crypto/BIO_should_retry.pod deleted file mode 100644 index b6d51f7..0000000 --- a/openssl/doc/crypto/BIO_should_retry.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -BIO_should_retry, 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 retry functions - -=head1 SYNOPSIS - - #include <openssl/bio.h> - - #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ) - #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE) - #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL) - #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS) - #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY) - - #define BIO_FLAGS_READ 0x01 - #define BIO_FLAGS_WRITE 0x02 - #define BIO_FLAGS_IO_SPECIAL 0x04 - #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) - #define BIO_FLAGS_SHOULD_RETRY 0x08 - - BIO * BIO_get_retry_BIO(BIO *bio, int *reason); - int BIO_get_retry_reason(BIO *bio); - -=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(). - -=head1 NOTES - -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 - -TBA diff --git a/openssl/doc/crypto/BN_BLINDING_new.pod b/openssl/doc/crypto/BN_BLINDING_new.pod deleted file mode 100644 index 06d7ea2..0000000 --- a/openssl/doc/crypto/BN_BLINDING_new.pod +++ /dev/null @@ -1,115 +0,0 @@ -=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_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_thread_id, 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); - #ifndef OPENSSL_NO_DEPRECATED - unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); - void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); - #endif - CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *); - 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. - -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_thread_id() provides access to the B<CRYPTO_THREADID> -object within the B<BN_BLINDING> structure. This is to help users -provide proper locking if needed for multi-threaded use. The "thread -id" object of a newly allocated B<BN_BLINDING> structure is -initialised to the thread id in which BN_BLINDING_new() was called. - -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_thread_id() returns a pointer to the thread id object -within a B<BN_BLINDING> object. - -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 SEE ALSO - -L<bn(3)|bn(3)> - -=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. - -BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id, -BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags -and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8 - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/openssl/doc/crypto/BN_CTX_new.pod b/openssl/doc/crypto/BN_CTX_new.pod deleted file mode 100644 index bbedbb1..0000000 --- a/openssl/doc/crypto/BN_CTX_new.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BN_CTX *BN_CTX_new(void); - - void BN_CTX_free(BN_CTX *c); - -Deprecated: - - void BN_CTX_init(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_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)|BN_CTX_start(3)> has been used on the B<BN_CTX>, -L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX> -may be freed by BN_CTX_free(). - -BN_CTX_init() (deprecated) initializes an existing uninitialized B<BN_CTX>. -This should not be used for new programs. Use BN_CTX_new() instead. - -=head1 RETURN VALUES - -BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails, -it returns B<NULL> and sets an error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. - -BN_CTX_init() and BN_CTX_free() have no return values. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_start(3)|BN_CTX_start(3)> - -=head1 HISTORY - -BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay -and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b. - -=cut diff --git a/openssl/doc/crypto/BN_CTX_start.pod b/openssl/doc/crypto/BN_CTX_start.pod deleted file mode 100644 index dfcefe1..0000000 --- a/openssl/doc/crypto/BN_CTX_start.pod +++ /dev/null @@ -1,52 +0,0 @@ -=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)|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)|ERR_get_error(3)>. - - -=head1 SEE ALSO - -L<BN_CTX_new(3)|BN_CTX_new(3)> - -=head1 HISTORY - -BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5. - -=cut diff --git a/openssl/doc/crypto/BN_add.pod b/openssl/doc/crypto/BN_add.pod deleted file mode 100644 index 88c7a79..0000000 --- a/openssl/doc/crypto/BN_add.pod +++ /dev/null @@ -1,126 +0,0 @@ -=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>). - -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_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)|BN_mod_mul_montgomery(3)> and -L<BN_mod_mul_reciprocal(3)|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)|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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, -L<BN_add_word(3)|BN_add_word(3)>, L<BN_set_bit(3)|BN_set_bit(3)> - -=head1 HISTORY - -BN_add(), BN_sub(), BN_sqr(), BN_div(), BN_mod(), BN_mod_mul(), -BN_mod_exp() and BN_gcd() are available in all versions of SSLeay and -OpenSSL. The I<ctx> argument to BN_mul() was added in SSLeay -0.9.1b. BN_exp() appeared in SSLeay 0.9.0. -BN_nnmod(), BN_mod_add(), BN_mod_sub(), and BN_mod_sqr() were added in -OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/BN_add_word.pod b/openssl/doc/crypto/BN_add_word.pod deleted file mode 100644 index 70667d2..0000000 --- a/openssl/doc/crypto/BN_add_word.pod +++ /dev/null @@ -1,61 +0,0 @@ -=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)|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<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)> - -=head1 HISTORY - -BN_add_word() and BN_mod_word() are available in all versions of -SSLeay and OpenSSL. BN_div_word() was added in SSLeay 0.8, and -BN_sub_word() and BN_mul_word() in SSLeay 0.9.0. - -Before 0.9.8a the return value for BN_div_word() and BN_mod_word() -in case of an error was 0. - -=cut diff --git a/openssl/doc/crypto/BN_bn2bin.pod b/openssl/doc/crypto/BN_bn2bin.pod deleted file mode 100644 index 3bed47f..0000000 --- a/openssl/doc/crypto/BN_bn2bin.pod +++ /dev/null @@ -1,97 +0,0 @@ -=pod - -=head1 NAME - -BN_bn2bin, BN_bin2bn, 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); - BIGNUM *BN_bin2bn(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_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_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() converts the string B<str> containing a hexadecimal number -to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new -B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's -length in hexadecimal digits. If the string starts with '-', the -number is negative. -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_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL -on error. BN_hex2bn() and BN_dec2bn() return the number's length in -hexadecimal or decimal digits, and 0 on error. - -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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_zero(3)|BN_zero(3)>, -L<ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3)>, -L<BN_num_bytes(3)|BN_num_bytes(3)> - -=head1 HISTORY - -BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available -in all versions of SSLeay and OpenSSL. - -BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and -BN_mpi2bn() were added in SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/BN_cmp.pod b/openssl/doc/crypto/BN_cmp.pod deleted file mode 100644 index 23e9ed0..0000000 --- a/openssl/doc/crypto/BN_cmp.pod +++ /dev/null @@ -1,48 +0,0 @@ -=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 SEE ALSO - -L<bn(3)|bn(3)> - -=head1 HISTORY - -BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are -available in all versions of SSLeay and OpenSSL. -BN_is_odd() was added in SSLeay 0.8. - -=cut diff --git a/openssl/doc/crypto/BN_copy.pod b/openssl/doc/crypto/BN_copy.pod deleted file mode 100644 index 388dd7d..0000000 --- a/openssl/doc/crypto/BN_copy.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -BN_copy, BN_dup - copy BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from); - - BIGNUM *BN_dup(const BIGNUM *from); - -=head1 DESCRIPTION - -BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM> -containing the value B<from>. - -=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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/BN_generate_prime.pod b/openssl/doc/crypto/BN_generate_prime.pod deleted file mode 100644 index bf1b530..0000000 --- a/openssl/doc/crypto/BN_generate_prime.pod +++ /dev/null @@ -1,150 +0,0 @@ -=pod - -=head1 NAME - -BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, -BN_GENCB_set_old, BN_GENCB_set, 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); - - #define BN_GENCB_set_old(gencb, callback, cb_arg) ... - - #define BN_GENCB_set(gencb, callback, cb_arg) ... - - -Deprecated: - - 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); - -=head1 DESCRIPTION - -BN_generate_prime_ex() generates a pseudo-random prime number of -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 4 - -=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. - -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. - -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. - -Callback functions should return 1 on success or 0 on error. - -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)> - -=head1 HISTORY - -The B<cb_arg> arguments to BN_generate_prime() and to BN_is_prime() -were added in SSLeay 0.9.0. The B<ret> argument to BN_generate_prime() -was added in SSLeay 0.9.1. -BN_is_prime_fasttest() was added in OpenSSL 0.9.5. - -=cut diff --git a/openssl/doc/crypto/BN_mod_inverse.pod b/openssl/doc/crypto/BN_mod_inverse.pod deleted file mode 100644 index 3ea3975..0000000 --- a/openssl/doc/crypto/BN_mod_inverse.pod +++ /dev/null @@ -1,36 +0,0 @@ -=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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)> - -=head1 HISTORY - -BN_mod_inverse() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/BN_mod_mul_montgomery.pod b/openssl/doc/crypto/BN_mod_mul_montgomery.pod deleted file mode 100644 index 6b16351..0000000 --- a/openssl/doc/crypto/BN_mod_mul_montgomery.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init, -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_init(BN_MONT_CTX *ctx); - 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)|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_init() initializes an existing uninitialized B<BN_MONT_CTX>. - -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. - -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. - -The B<BN_MONT_CTX> structure is defined as follows: - - typedef struct bn_mont_ctx_st - { - int ri; /* number of bits in R */ - BIGNUM RR; /* R^2 (used to convert to Montgomery form) */ - BIGNUM N; /* The modulus */ - BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1 - * (Ni is only stored for bignum algorithm) */ - BN_ULONG n0; /* least significant word of Ni */ - int flags; - } BN_MONT_CTX; - -BN_to_montgomery() is a macro. - -=head1 RETURN VALUES - -BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL -on error. - -BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values. - -For the other functions, 1 is returned for success, 0 on error. -The error codes can be obtained by L<ERR_get_error(3)|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<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_new(3)|BN_CTX_new(3)> - -=head1 HISTORY - -BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(), -BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery() -are available in all versions of SSLeay and OpenSSL. - -BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b. - -=cut diff --git a/openssl/doc/crypto/BN_mod_mul_reciprocal.pod b/openssl/doc/crypto/BN_mod_mul_reciprocal.pod deleted file mode 100644 index 74a216d..0000000 --- a/openssl/doc/crypto/BN_mod_mul_reciprocal.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init, -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_init(BN_RECP_CTX *recp); - 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)|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_init() initializes an existing uninitialized B<BN_RECP>. - -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. - -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 is defined as follows: - - typedef struct bn_recp_ctx_st - { - BIGNUM N; /* the divisor */ - BIGNUM Nr; /* the reciprocal */ - int num_bits; - int shift; - int flags; - } BN_RECP_CTX; - -It 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_init() and BN_RECP_CTX_free() have no return values. - -For the other functions, 1 is returned for success, 0 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_new(3)|BN_CTX_new(3)> - -=head1 HISTORY - -B<BN_RECP_CTX> was added in SSLeay 0.9.0. Before that, the function -BN_reciprocal() was used instead, and the BN_mod_mul_reciprocal() -arguments were different. - -=cut diff --git a/openssl/doc/crypto/BN_new.pod b/openssl/doc/crypto/BN_new.pod deleted file mode 100644 index ab7a105..0000000 --- a/openssl/doc/crypto/BN_new.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_new(void); - - void BN_init(BIGNUM *); - - 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_init() -initializes an existing uninitialized B<BIGNUM>. - -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. - -=head1 RETURN VALUES - -BN_new() returns a pointer to the B<BIGNUM>. If the allocation fails, -it returns B<NULL> and sets an error code that can be obtained -by L<ERR_get_error(3)|ERR_get_error(3)>. - -BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return -values. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in -all versions on SSLeay and OpenSSL. BN_init() was added in SSLeay -0.9.1b. - -=cut diff --git a/openssl/doc/crypto/BN_num_bytes.pod b/openssl/doc/crypto/BN_num_bytes.pod deleted file mode 100644 index a6a2e3f..0000000 --- a/openssl/doc/crypto/BN_num_bytes.pod +++ /dev/null @@ -1,57 +0,0 @@ -=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<bn(3)|bn(3)>, L<DH_size(3)|DH_size(3)>, L<DSA_size(3)|DSA_size(3)>, -L<RSA_size(3)|RSA_size(3)> - -=head1 HISTORY - -BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in -all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/BN_rand.pod b/openssl/doc/crypto/BN_rand.pod deleted file mode 100644 index a1513a9..0000000 --- a/openssl/doc/crypto/BN_rand.pod +++ /dev/null @@ -1,63 +0,0 @@ -=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 -accomodate the requirements specified by the B<top> and B<bottom> -parameters, an error is returned. -If B<top> is -1, the -most significant bit of the random number can be zero. If B<top> is 0, -it is set to 1, and if B<top> is 1, 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 true, the -number will be odd. The value of B<bits> must be zero or greater. If B<bits> is -1 then B<top> cannot also be 1. - -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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)> - -=head1 HISTORY - -BN_rand() is available in all versions of SSLeay and OpenSSL. -BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case -and the function BN_rand_range() were added in OpenSSL 0.9.6a. -BN_pseudo_rand_range() was added in OpenSSL 0.9.6c. - -=cut diff --git a/openssl/doc/crypto/BN_set_bit.pod b/openssl/doc/crypto/BN_set_bit.pod deleted file mode 100644 index a32cca2..0000000 --- a/openssl/doc/crypto/BN_set_bit.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, L<BN_add(3)|BN_add(3)> - -=head1 HISTORY - -BN_set_bit(), BN_clear_bit(), BN_is_bit_set(), BN_mask_bits(), -BN_lshift(), BN_lshift1(), BN_rshift(), and BN_rshift1() are available -in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/BN_swap.pod b/openssl/doc/crypto/BN_swap.pod deleted file mode 100644 index 79efaa1..0000000 --- a/openssl/doc/crypto/BN_swap.pod +++ /dev/null @@ -1,23 +0,0 @@ -=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>. - -L<bn(3)|bn(3)> - -=head1 HISTORY - -BN_swap was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/BN_zero.pod b/openssl/doc/crypto/BN_zero.pod deleted file mode 100644 index b555ec3..0000000 --- a/openssl/doc/crypto/BN_zero.pod +++ /dev/null @@ -1,59 +0,0 @@ -=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> - - int BN_zero(BIGNUM *a); - int BN_one(BIGNUM *a); - - const BIGNUM *BN_value_one(void); - - int BN_set_word(BIGNUM *a, unsigned long w); - unsigned long BN_get_word(BIGNUM *a); - -=head1 DESCRIPTION - -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 an unsigned -long. - -=head1 RETURN VALUES - -BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot -be represented as an unsigned long. - -BN_zero(), BN_one() and BN_set_word() return 1 on success, 0 otherwise. -BN_value_one() returns the constant. - -=head1 BUGS - -Someone might change the constant. - -If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an -unsigned long but this value is also returned on error. - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> - -=head1 HISTORY - -BN_zero(), BN_one() and BN_set_word() are available in all versions of -SSLeay and OpenSSL. BN_value_one() and BN_get_word() were added in -SSLeay 0.8. - -BN_value_one() was changed to return a true const BIGNUM * in OpenSSL -0.9.7. - -=cut diff --git a/openssl/doc/crypto/CMS_add0_cert.pod b/openssl/doc/crypto/CMS_add0_cert.pod deleted file mode 100644 index 8678ca1..0000000 --- a/openssl/doc/crypto/CMS_add0_cert.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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)|ERR_get_error(3)>, -L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_encrypt(3)|CMS_encrypt(3)> - -=head1 HISTORY - -CMS_add0_cert(), CMS_add1_cert(), CMS_get1_certs(), CMS_add0_crl() -and CMS_get1_crls() were all first added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_add1_recipient_cert.pod b/openssl/doc/crypto/CMS_add1_recipient_cert.pod deleted file mode 100644 index d7d8e25..0000000 --- a/openssl/doc/crypto/CMS_add1_recipient_cert.pod +++ /dev/null @@ -1,62 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>, -L<CMS_final(3)|CMS_final(3)>, - -=head1 HISTORY - -CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL -0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_add1_signer.pod b/openssl/doc/crypto/CMS_add1_signer.pod deleted file mode 100644 index a055b82..0000000 --- a/openssl/doc/crypto/CMS_add1_signer.pod +++ /dev/null @@ -1,101 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_final(3)|CMS_final(3)>, - -=head1 HISTORY - -CMS_add1_signer() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_compress.pod b/openssl/doc/crypto/CMS_compress.pod deleted file mode 100644 index 0a07152..0000000 --- a/openssl/doc/crypto/CMS_compress.pod +++ /dev/null @@ -1,73 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_uncompress(3)|CMS_uncompress(3)> - -=head1 HISTORY - -CMS_compress() was added to OpenSSL 0.9.8 -The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/CMS_decrypt.pod b/openssl/doc/crypto/CMS_decrypt.pod deleted file mode 100644 index 3fa9212..0000000 --- a/openssl/doc/crypto/CMS_decrypt.pod +++ /dev/null @@ -1,79 +0,0 @@ -=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 - -OpenSSL_add_all_algorithms() (or equivalent) should be called before using this -function or errors about unknown algorithms will occur. - -Although the recipients certificate is not needed to decrypt the data it is -needed to locate the appropriate (of possible several) recipients in the CMS -structure. - -If B<cert> is set to NULL all possible recipients are tried. 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)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> - -=head1 HISTORY - -CMS_decrypt() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_encrypt.pod b/openssl/doc/crypto/CMS_encrypt.pod deleted file mode 100644 index 1ee5b27..0000000 --- a/openssl/doc/crypto/CMS_encrypt.pod +++ /dev/null @@ -1,96 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> - -=head1 HISTORY - -CMS_decrypt() was added to OpenSSL 0.9.8 -The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/CMS_final.pod b/openssl/doc/crypto/CMS_final.pod deleted file mode 100644 index 36cf96b..0000000 --- a/openssl/doc/crypto/CMS_final.pod +++ /dev/null @@ -1,41 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_encrypt(3)|CMS_encrypt(3)> - -=head1 HISTORY - -CMS_final() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_get0_RecipientInfos.pod b/openssl/doc/crypto/CMS_get0_RecipientInfos.pod deleted file mode 100644 index fe49772..0000000 --- a/openssl/doc/crypto/CMS_get0_RecipientInfos.pod +++ /dev/null @@ -1,120 +0,0 @@ -=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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> - -=head1 HISTORY - -These functions were first was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_get0_SignerInfos.pod b/openssl/doc/crypto/CMS_get0_SignerInfos.pod deleted file mode 100644 index b46c0e0..0000000 --- a/openssl/doc/crypto/CMS_get0_SignerInfos.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=head1 NAME - -CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp, CMS_set1_signer_cert - 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)|ERR_get_error(3)> - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)> - -=head1 HISTORY - -These functions were first was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_get0_type.pod b/openssl/doc/crypto/CMS_get0_type.pod deleted file mode 100644 index 3ed92bd..0000000 --- a/openssl/doc/crypto/CMS_get0_type.pod +++ /dev/null @@ -1,77 +0,0 @@ -=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(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)|ERR_get_error(3)> - -=head1 HISTORY - -CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all -first added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod b/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod deleted file mode 100644 index f546376..0000000 --- a/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod +++ /dev/null @@ -1,69 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, L<CMS_verify(3)|CMS_verify(3)> -L<CMS_verify_receipt(3)|CMS_verify_receipt(3)> - -=head1 HISTORY - -CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), -CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to -OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_sign.pod b/openssl/doc/crypto/CMS_sign.pod deleted file mode 100644 index 2cc72de..0000000 --- a/openssl/doc/crypto/CMS_sign.pod +++ /dev/null @@ -1,121 +0,0 @@ -=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. B<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)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)> - -=head1 HISTORY - -CMS_sign() was added to OpenSSL 0.9.8 - -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. - -=cut diff --git a/openssl/doc/crypto/CMS_sign_receipt.pod b/openssl/doc/crypto/CMS_sign_receipt.pod deleted file mode 100644 index cae1f83..0000000 --- a/openssl/doc/crypto/CMS_sign_receipt.pod +++ /dev/null @@ -1,45 +0,0 @@ -=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)|ERR_get_error(3)>, -L<CMS_verify_receipt(3)|CMS_verify_receipt(3)>, -L<CMS_sign(3)|CMS_sign(3)> - -=head1 HISTORY - -CMS_sign_receipt() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_uncompress.pod b/openssl/doc/crypto/CMS_uncompress.pod deleted file mode 100644 index c6056b0..0000000 --- a/openssl/doc/crypto/CMS_uncompress.pod +++ /dev/null @@ -1,54 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_compress(3)|CMS_compress(3)> - -=head1 HISTORY - -CMS_uncompress() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_verify.pod b/openssl/doc/crypto/CMS_verify.pod deleted file mode 100644 index 7a2c1ee..0000000 --- a/openssl/doc/crypto/CMS_verify.pod +++ /dev/null @@ -1,126 +0,0 @@ -=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)|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)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)> - -=head1 HISTORY - -CMS_verify() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CMS_verify_receipt.pod b/openssl/doc/crypto/CMS_verify_receipt.pod deleted file mode 100644 index 9283e0e..0000000 --- a/openssl/doc/crypto/CMS_verify_receipt.pod +++ /dev/null @@ -1,47 +0,0 @@ -=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)|ERR_get_error(3)> - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, -L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, -L<CMS_verify(3)|CMS_verify(3)>, - -=head1 HISTORY - -CMS_verify_receipt() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/CONF_modules_free.pod b/openssl/doc/crypto/CONF_modules_free.pod deleted file mode 100644 index 347020c..0000000 --- a/openssl/doc/crypto/CONF_modules_free.pod +++ /dev/null @@ -1,47 +0,0 @@ -=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_free(void); - void CONF_modules_finish(void); - void CONF_modules_unload(int all); - -=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 applications will only call CONF_modules_free() at application to -tidy up any configuration performed. - -=head1 RETURN VALUE - -None of the functions return a value. - -=head1 SEE ALSO - -L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, -L<CONF_modules_load_file(3)|CONF_modules_load_file(3)> - -=head1 HISTORY - -CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish() -first appeared in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/CONF_modules_load_file.pod b/openssl/doc/crypto/CONF_modules_load_file.pod deleted file mode 100644 index cc0b537..0000000 --- a/openssl/doc/crypto/CONF_modules_load_file.pod +++ /dev/null @@ -1,137 +0,0 @@ -=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 cutomized using B<flags>. - -CONF_modules_load() is idential 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. - -Applications should call these functions after loading builtin modules using -OPENSSL_load_builtin_modules(), any ENGINEs for example using -ENGINE_load_builtin_engines(), any algorithms for example -OPENSSL_add_all_algorithms() and (if the application uses libssl) -SSL_library_init(). - -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<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, -L<CONF_free(3)|CONF_free(3)>, L<err(3)|err(3)> - -=head1 HISTORY - -CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/CRYPTO_set_ex_data.pod b/openssl/doc/crypto/CRYPTO_set_ex_data.pod deleted file mode 100644 index 7409c02..0000000 --- a/openssl/doc/crypto/CRYPTO_set_ex_data.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/crypto.h> - - int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); - - void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -These functions should only be used by applications to manipulate -B<CRYPTO_EX_DATA> structures passed to the B<new_func()>, B<free_func()> and -B<dup_func()> callbacks: as passed to B<RSA_get_ex_new_index()> for example. - -B<CRYPTO_set_ex_data()> is used to set application specific data, the data is -supplied in the B<arg> parameter and its precise meaning is up to the -application. - -B<CRYPTO_get_ex_data()> is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous B<CRYPTO_set_ex_data()> call. - -=head1 RETURN VALUES - -B<CRYPTO_set_ex_data()> returns 1 on success or 0 on failure. - -B<CRYPTO_get_ex_data()> returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid B<idx> -parameter. - -On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, -L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)> - -=head1 HISTORY - -CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/DH_generate_key.pod b/openssl/doc/crypto/DH_generate_key.pod deleted file mode 100644 index 81f09fd..0000000 --- a/openssl/doc/crypto/DH_generate_key.pod +++ /dev/null @@ -1,50 +0,0 @@ -=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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<DH_size(3)|DH_size(3)> - -=head1 HISTORY - -DH_generate_key() and DH_compute_key() are available in all versions -of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/DH_generate_parameters.pod b/openssl/doc/crypto/DH_generate_parameters.pod deleted file mode 100644 index 7f81a04..0000000 --- a/openssl/doc/crypto/DH_generate_parameters.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - - -DH_generate_parameters_ex, DH_generate_parameters, -DH_check - 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); - -Deprecated: - - DH *DH_generate_parameters(int prime_len, int generator, - void (*callback)(int, int, void *), void *cb_arg); - -=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)|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)|BN_generate_prime(3)> for information on -the BN_GENCB_call() function. - -DH_check() validates Diffie-Hellman parameters. It checks that B<p> is -a safe prime, and that B<g> is a suitable generator. In the case of an -error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or -DH_NOT_SUITABLE_GENERATOR are set in B<*codes>. -DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be -checked, i.e. it does not equal 2 or 5. - -=head1 RETURN VALUES - -DH_generate_parameters_ex() and DH_check() 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)|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 BUGS - -If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not -a usable generator. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DH_free(3)|DH_free(3)> - -=head1 HISTORY - -DH_check() is available in all versions of SSLeay and OpenSSL. -The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0. - -In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used -instead of DH_CHECK_P_NOT_SAFE_PRIME. - -=cut diff --git a/openssl/doc/crypto/DH_get_ex_new_index.pod b/openssl/doc/crypto/DH_get_ex_new_index.pod deleted file mode 100644 index fa5eab2..0000000 --- a/openssl/doc/crypto/DH_get_ex_new_index.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - int DH_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DH_set_ex_data(DH *d, int idx, void *arg); - - char *DH_get_ex_data(DH *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DH -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L<RSA_get_ex_new_index(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dh(3)|dh(3)> - -=head1 HISTORY - -DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are -available since OpenSSL 0.9.5. - -=cut diff --git a/openssl/doc/crypto/DH_new.pod b/openssl/doc/crypto/DH_new.pod deleted file mode 100644 index 60c9300..0000000 --- a/openssl/doc/crypto/DH_new.pod +++ /dev/null @@ -1,40 +0,0 @@ -=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. - -=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)|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)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DH_generate_parameters(3)|DH_generate_parameters(3)>, -L<DH_generate_key(3)|DH_generate_key(3)> - -=head1 HISTORY - -DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/DH_set_method.pod b/openssl/doc/crypto/DH_set_method.pod deleted file mode 100644 index d5cdc3b..0000000 --- a/openssl/doc/crypto/DH_set_method.pod +++ /dev/null @@ -1,129 +0,0 @@ -=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> - #include <openssl/engine.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. - -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. - -=head1 THE DH_METHOD STRUCTURE - - typedef struct dh_meth_st - { - /* name of the implementation */ - const char *name; - - /* generate private and public DH values for key agreement */ - int (*generate_key)(DH *dh); - - /* compute shared secret */ - int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, - BN_MONT_CTX *m_ctx); - - /* called at DH_new */ - int (*init)(DH *dh); - - /* called at DH_free */ - int (*finish)(DH *dh); - - int flags; - - char *app_data; /* ?? */ - - } DH_METHOD; - -=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)|ERR_get_error(3)> if the allocation fails. Otherwise it -returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, DH_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 DH functionality using an ENGINE API function, -that will override any DH defaults set using the DH API (ie. -DH_set_default_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in DH and other cryptographic -algorithms. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> - -=head1 HISTORY - -DH_set_default_method(), DH_get_default_method(), DH_set_method(), -DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. - -DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced -DH_set_default_method() and DH_get_default_method() respectively, and -DH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than -B<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE API was restructured so that this -change was reversed, and behaviour of the other functions resembled more closely -the previous behaviour. The behaviour of defaults in the ENGINE API now -transparently overrides the behaviour of defaults in the DH API without -requiring changing these function prototypes. - -=cut diff --git a/openssl/doc/crypto/DH_size.pod b/openssl/doc/crypto/DH_size.pod deleted file mode 100644 index 97f26fd..0000000 --- a/openssl/doc/crypto/DH_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -DH_size - get Diffie-Hellman prime size - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - int DH_size(DH *dh); - -=head1 DESCRIPTION - -This function returns the Diffie-Hellman size in bytes. It can be used -to determine how much memory must be allocated for the shared secret -computed by DH_compute_key(). - -B<dh-E<gt>p> must not be B<NULL>. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)> - -=head1 HISTORY - -DH_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/DSA_SIG_new.pod b/openssl/doc/crypto/DSA_SIG_new.pod deleted file mode 100644 index 3ac6140..0000000 --- a/openssl/doc/crypto/DSA_SIG_new.pod +++ /dev/null @@ -1,40 +0,0 @@ -=pod - -=head1 NAME - -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); - -=head1 DESCRIPTION - -DSA_SIG_new() allocates and initializes a 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. - -=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)|ERR_get_error(3)>. Otherwise it returns a pointer -to the newly allocated structure. - -DSA_SIG_free() returns no value. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DSA_do_sign(3)|DSA_do_sign(3)> - -=head1 HISTORY - -DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3. - -=cut diff --git a/openssl/doc/crypto/DSA_do_sign.pod b/openssl/doc/crypto/DSA_do_sign.pod deleted file mode 100644 index 5dfc733..0000000 --- a/openssl/doc/crypto/DSA_do_sign.pod +++ /dev/null @@ -1,47 +0,0 @@ -=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)|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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_SIG_new(3)|DSA_SIG_new(3)>, -L<DSA_sign(3)|DSA_sign(3)> - -=head1 HISTORY - -DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3. - -=cut diff --git a/openssl/doc/crypto/DSA_dup_DH.pod b/openssl/doc/crypto/DSA_dup_DH.pod deleted file mode 100644 index 7f6f0d1..0000000 --- a/openssl/doc/crypto/DSA_dup_DH.pod +++ /dev/null @@ -1,36 +0,0 @@ -=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)|ERR_get_error(3)>. - -=head1 NOTE - -Be careful to avoid small subgroup attacks when using this. - -=head1 SEE ALSO - -L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -DSA_dup_DH() was added in OpenSSL 0.9.4. - -=cut diff --git a/openssl/doc/crypto/DSA_generate_key.pod b/openssl/doc/crypto/DSA_generate_key.pod deleted file mode 100644 index af83ccf..0000000 --- a/openssl/doc/crypto/DSA_generate_key.pod +++ /dev/null @@ -1,34 +0,0 @@ -=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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)> - -=head1 HISTORY - -DSA_generate_key() is available since SSLeay 0.8. - -=cut diff --git a/openssl/doc/crypto/DSA_generate_parameters.pod b/openssl/doc/crypto/DSA_generate_parameters.pod deleted file mode 100644 index b1a4d20..0000000 --- a/openssl/doc/crypto/DSA_generate_parameters.pod +++ /dev/null @@ -1,121 +0,0 @@ -=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: - - 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); - -=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 to be generated; the DSS allows a -maximum of 1024 bits. - -If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be -generated at random. Otherwise, the seed is used to generate -them. If the given seed does not yield a prime q, a new random -seed is chosen. - -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)|BN_generate_prime(3)>. - -=over 4 - -=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)|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)|ERR_get_error(3)>. - -=head1 BUGS - -Seed lengths E<gt> 20 are not supported. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_free(3)|DSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)> - -=head1 HISTORY - -DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg> -argument was added in SSLeay 0.9.0. -In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called -in the inner loop of the Miller-Rabin test whenever it reached the -squaring step (the parameters to B<callback> did not reveal how many -witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)> -is called as in BN_is_prime(3), i.e. once for each witness. -=cut diff --git a/openssl/doc/crypto/DSA_get_ex_new_index.pod b/openssl/doc/crypto/DSA_get_ex_new_index.pod deleted file mode 100644 index fb6efc1..0000000 --- a/openssl/doc/crypto/DSA_get_ex_new_index.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - int DSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DSA_set_ex_data(DSA *d, int idx, void *arg); - - char *DSA_get_ex_data(DSA *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DSA -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L<RSA_get_ex_new_index(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)> - -=head1 HISTORY - -DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are -available since OpenSSL 0.9.5. - -=cut diff --git a/openssl/doc/crypto/DSA_new.pod b/openssl/doc/crypto/DSA_new.pod deleted file mode 100644 index 48e9b82..0000000 --- a/openssl/doc/crypto/DSA_new.pod +++ /dev/null @@ -1,42 +0,0 @@ -=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. - -=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)|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)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, -L<DSA_generate_key(3)|DSA_generate_key(3)> - -=head1 HISTORY - -DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/DSA_set_method.pod b/openssl/doc/crypto/DSA_set_method.pod deleted file mode 100644 index 9c1434b..0000000 --- a/openssl/doc/crypto/DSA_set_method.pod +++ /dev/null @@ -1,143 +0,0 @@ -=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> - #include <openssl/engine.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. - -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. - -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 THE DSA_METHOD STRUCTURE - -struct - { - /* name of the implementation */ - const char *name; - - /* sign */ - DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, - DSA *dsa); - - /* pre-compute k^-1 and r */ - int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, - BIGNUM **rp); - - /* verify */ - int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - - /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some - implementations) */ - int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, - BIGNUM *a2, BIGNUM *p2, BIGNUM *m, - BN_CTX *ctx, BN_MONT_CTX *in_mont); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, - const BIGNUM *p, const BIGNUM *m, - BN_CTX *ctx, BN_MONT_CTX *m_ctx); - - /* called at DSA_new */ - int (*init)(DSA *DSA); - - /* called at DSA_free */ - int (*finish)(DSA *DSA); - - int flags; - - char *app_data; /* ?? */ - - } DSA_METHOD; - -=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)|ERR_get_error(3)> if the allocation -fails. Otherwise it returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, DSA_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 DSA functionality using an ENGINE API function, -that will override any DSA defaults set using the DSA API (ie. -DSA_set_default_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in DSA and other cryptographic -algorithms. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)> - -=head1 HISTORY - -DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), -DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. - -DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced -DSA_set_default_method() and DSA_get_default_method() respectively, and -DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than -B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE API was restructured so that this -change was reversed, and behaviour of the other functions resembled more closely -the previous behaviour. The behaviour of defaults in the ENGINE API now -transparently overrides the behaviour of defaults in the DSA API without -requiring changing these function prototypes. - -=cut diff --git a/openssl/doc/crypto/DSA_sign.pod b/openssl/doc/crypto/DSA_sign.pod deleted file mode 100644 index 97389e8..0000000 --- a/openssl/doc/crypto/DSA_sign.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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)|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)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_do_sign(3)|DSA_do_sign(3)> - -=head1 HISTORY - -DSA_sign() and DSA_verify() are available in all versions of SSLeay. -DSA_sign_setup() was added in SSLeay 0.8. - -=cut diff --git a/openssl/doc/crypto/DSA_size.pod b/openssl/doc/crypto/DSA_size.pod deleted file mode 100644 index ba4f650..0000000 --- a/openssl/doc/crypto/DSA_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -DSA_size - get DSA signature size - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - int DSA_size(const DSA *dsa); - -=head1 DESCRIPTION - -This function returns the size of an ASN.1 encoded DSA signature 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>. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)> - -=head1 HISTORY - -DSA_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/EC_GFp_simple_method.pod b/openssl/doc/crypto/EC_GFp_simple_method.pod deleted file mode 100644 index aff20ac..0000000 --- a/openssl/doc/crypto/EC_GFp_simple_method.pod +++ /dev/null @@ -1,60 +0,0 @@ -=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 B<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)|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)|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)|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(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>, -L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> - -=cut diff --git a/openssl/doc/crypto/EC_GROUP_copy.pod b/openssl/doc/crypto/EC_GROUP_copy.pod deleted file mode 100644 index 49dc01c..0000000 --- a/openssl/doc/crypto/EC_GROUP_copy.pod +++ /dev/null @@ -1,174 +0,0 @@ -=pod - -=head1 NAME - -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 B<EC_GROUP> objects. - -=head1 SYNOPSIS - - #include <openssl/ec.h> - #include <openssl/bn.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); - int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); - - 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 paramaters that must be agreed by all participants using the curve. These -paramaters 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> multipied 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)|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 on a curve is used to determine whether there is a specific ASN1 OID to describe the curve or not. -If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID. If not then asn1_flag is 0. 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. If set then -the curve_name must also be set. - -The point_coversion_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 0x02 */ - 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>. Similary -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_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(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> - -=cut diff --git a/openssl/doc/crypto/EC_GROUP_new.pod b/openssl/doc/crypto/EC_GROUP_new.pod deleted file mode 100644 index ff55bf3..0000000 --- a/openssl/doc/crypto/EC_GROUP_new.pod +++ /dev/null @@ -1,95 +0,0 @@ -=pod - -=head1 NAME - -EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, 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 B<EC_GROUP> objects. - -=head1 SYNOPSIS - - #include <openssl/ec.h> - #include <openssl/bn.h> - - EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); - 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); - - 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)|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_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 polybnomial - each bit represents a term in the polynomial. Therefore there will either be three -or five bits set dependant 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. - -EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. - -=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(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> - -=cut diff --git a/openssl/doc/crypto/EC_KEY_new.pod b/openssl/doc/crypto/EC_KEY_new.pod deleted file mode 100644 index 0fa2de1..0000000 --- a/openssl/doc/crypto/EC_KEY_new.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=head1 NAME - -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_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_get_key_method_data, EC_KEY_insert_key_method_data, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates - Functions for creating, destroying and manipulating B<EC_KEY> objects. - -=head1 SYNOPSIS - - #include <openssl/ec.h> - #include <openssl/bn.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_get_key_method_data(EC_KEY *key, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - 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); - -=head1 DESCRIPTION - -An EC_KEY represents a public key and (optionaly) an 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. Refer to L<EC_GROUP_new(3)|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. - -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 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 will 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 refer to L<EC_POINT_new(3)|EC_POINT_new(3)>. - -EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitrary additional data specific to the -elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B<data> parameter, which must have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted. - -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 currently defined standard flags 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 and is defined in ecdh.h. 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)|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_POINT_add(3)>. - - -=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 and EC_KEY_set_public_key_affine_coordinates 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. - - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, -L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>, -L<EC_POINT_add(3)|EC_POINT_add(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, -L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> - -=cut diff --git a/openssl/doc/crypto/EC_POINT_add.pod b/openssl/doc/crypto/EC_POINT_add.pod deleted file mode 100644 index ae92640..0000000 --- a/openssl/doc/crypto/EC_POINT_add.pod +++ /dev/null @@ -1,72 +0,0 @@ -=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 B<EC_POINT> objects. - -=head1 SYNOPSIS - - #include <openssl/ec.h> - #include <openssl/bn.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)|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(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> - -=cut diff --git a/openssl/doc/crypto/EC_POINT_new.pod b/openssl/doc/crypto/EC_POINT_new.pod deleted file mode 100644 index 858baf4..0000000 --- a/openssl/doc/crypto/EC_POINT_new.pod +++ /dev/null @@ -1,128 +0,0 @@ -=pod - -=head1 NAME - -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_set_Jprojective_coordinates, 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 B<EC_POINT> objects. - -=head1 SYNOPSIS - - #include <openssl/ec.h> - #include <openssl/bn.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); - 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 *, const EC_POINT *, - point_conversion_form_t form, BIGNUM *, BN_CTX *); - EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, - EC_POINT *, BN_CTX *); - char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BN_CTX *); - EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, - EC_POINT *, BN_CTX *); - - -=head1 DESCRIPTION - -An EC_POINT 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 EC_POINT. - -EC_POINT_clear_free destroys any sensitive data held within the EC_POINT and then frees its memory. - -EC_POINT_copy copies the point B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD. - -EC_POINT_dup creates a new EC_POINT object and copies the content from B<src> to the newly created -EC_POINT object. - -EC_POINT_method_of obtains the 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 to 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 EC_POINTs can be converted to and from various external -representations. Supported representations are octet strings, BIGNUMs and -hexadecimal. Octet strings are stored in a buffer along with an associated -buffer length. A point held in a BIGNUM is calculated by converting the point to -an octet string and then converting that octet string into a BIGNUM integer. -Points in hexadecimal format are stored in 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 string, BIGNUM and hexadecimal respectively. - -The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. 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_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 returns 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(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> - -=cut diff --git a/openssl/doc/crypto/ERR_GET_LIB.pod b/openssl/doc/crypto/ERR_GET_LIB.pod deleted file mode 100644 index 2a129da..0000000 --- a/openssl/doc/crypto/ERR_GET_LIB.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and -reason code - -=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); - -=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. - -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() and ERR_GET_REASON() are macros. - -=head1 RETURN VALUES - -The library number, function code and reason code respectively. - -=head1 SEE ALSO - -L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in -all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/ERR_clear_error.pod b/openssl/doc/crypto/ERR_clear_error.pod deleted file mode 100644 index 566e1f4..0000000 --- a/openssl/doc/crypto/ERR_clear_error.pod +++ /dev/null @@ -1,29 +0,0 @@ -=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(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -ERR_clear_error() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/ERR_error_string.pod b/openssl/doc/crypto/ERR_error_string.pod deleted file mode 100644 index cdfa7fe..0000000 --- a/openssl/doc/crypto/ERR_error_string.pod +++ /dev/null @@ -1,73 +0,0 @@ -=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 120 -bytes long. If I<buf> is B<NULL>, the error string is placed in a -static buffer. -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. - -The OpenSSL error strings should be loaded by calling -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL -applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> -first. -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)|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(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> -L<ERR_print_errors(3)|ERR_print_errors(3)> - -=head1 HISTORY - -ERR_error_string() is available in all versions of SSLeay and OpenSSL. -ERR_error_string_n() was added in OpenSSL 0.9.6. - -=cut diff --git a/openssl/doc/crypto/ERR_get_error.pod b/openssl/doc/crypto/ERR_get_error.pod deleted file mode 100644 index 01e196c..0000000 --- a/openssl/doc/crypto/ERR_get_error.pod +++ /dev/null @@ -1,79 +0,0 @@ -=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)|ERR_GET_LIB(3)> for obtaining information about -location and reason of the error, and -L<ERR_error_string(3)|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(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> - -=head1 HISTORY - -ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and -ERR_peek_error_line() are available in all versions of SSLeay and -OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data() -were added in SSLeay 0.9.0. -ERR_peek_last_error(), ERR_peek_last_error_line() and -ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/ERR_load_crypto_strings.pod b/openssl/doc/crypto/ERR_load_crypto_strings.pod deleted file mode 100644 index 9bdec75..0000000 --- a/openssl/doc/crypto/ERR_load_crypto_strings.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - -load and free error strings - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_load_crypto_strings(void); - void ERR_free_strings(void); - - #include <openssl/ssl.h> - - void SSL_load_error_strings(void); - -=head1 DESCRIPTION - -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. - -One of these functions should be called before generating -textual error messages. However, this is not required when memory -usage is an issue. - -ERR_free_strings() frees all previously loaded error strings. - -=head1 RETURN VALUES - -ERR_load_crypto_strings(), SSL_load_error_strings() and -ERR_free_strings() return no values. - -=head1 SEE ALSO - -L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)> - -=head1 HISTORY - -ERR_load_error_strings(), SSL_load_error_strings() and -ERR_free_strings() are available in all versions of SSLeay and -OpenSSL. - -=cut diff --git a/openssl/doc/crypto/ERR_load_strings.pod b/openssl/doc/crypto/ERR_load_strings.pod deleted file mode 100644 index 5acdd0e..0000000 --- a/openssl/doc/crypto/ERR_load_strings.pod +++ /dev/null @@ -1,54 +0,0 @@ -=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 a new library number. - -=head1 SEE ALSO - -L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> - -=head1 HISTORY - -ERR_load_error_strings() and ERR_PACK() are available in all versions -of SSLeay and OpenSSL. ERR_get_next_error_library() was added in -SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/ERR_print_errors.pod b/openssl/doc/crypto/ERR_print_errors.pod deleted file mode 100644 index b100a5f..0000000 --- a/openssl/doc/crypto/ERR_print_errors.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -ERR_print_errors, ERR_print_errors_fp - print error messages - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_print_errors(BIO *bp); - void ERR_print_errors_fp(FILE *fp); - -=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>. - - -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(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> - -=head1 HISTORY - -ERR_print_errors() and ERR_print_errors_fp() -are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/ERR_put_error.pod b/openssl/doc/crypto/ERR_put_error.pod deleted file mode 100644 index acd241f..0000000 --- a/openssl/doc/crypto/ERR_put_error.pod +++ /dev/null @@ -1,44 +0,0 @@ -=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, ...); - -=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. - -L<ERR_load_strings(3)|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. - -=head1 RETURN VALUES - -ERR_put_error() and ERR_add_error_data() return -no values. - -=head1 SEE ALSO - -L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> - -=head1 HISTORY - -ERR_put_error() is available in all versions of SSLeay and OpenSSL. -ERR_add_error_data() was added in SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/ERR_remove_state.pod b/openssl/doc/crypto/ERR_remove_state.pod deleted file mode 100644 index a4d38c1..0000000 --- a/openssl/doc/crypto/ERR_remove_state.pod +++ /dev/null @@ -1,45 +0,0 @@ -=pod - -=head1 NAME - -ERR_remove_thread_state, ERR_remove_state - free a thread's error queue - -=head1 SYNOPSIS - - #include <openssl/err.h> - - void ERR_remove_thread_state(const CRYPTO_THREADID *tid); - -Deprecated: - - void ERR_remove_state(unsigned long pid); - -=head1 DESCRIPTION - -ERR_remove_thread_state() frees the error queue associated with thread B<tid>. -If B<tid> == B<NULL>, the current thread will have its error queue removed. - -Since error queue data structures are allocated automatically for new -threads, they must be freed when threads are terminated in order to -avoid memory leaks. - -ERR_remove_state is deprecated and has been replaced by -ERR_remove_thread_state. Since threads in OpenSSL are no longer identified -by unsigned long values any argument to this function is ignored. Calling -ERR_remove_state is equivalent to B<ERR_remove_thread_state(NULL)>. - -=head1 RETURN VALUE - -ERR_remove_thread_state and ERR_remove_state() return no value. - -=head1 SEE ALSO - -L<err(3)|err(3)> - -=head1 HISTORY - -ERR_remove_state() is available in all versions of SSLeay and OpenSSL. It -was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state was introduced -and thread IDs were introduced to identify threads instead of 'unsigned long'. - -=cut diff --git a/openssl/doc/crypto/ERR_set_mark.pod b/openssl/doc/crypto/ERR_set_mark.pod deleted file mode 100644 index d3ca4f2..0000000 --- a/openssl/doc/crypto/ERR_set_mark.pod +++ /dev/null @@ -1,38 +0,0 @@ -=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 SEE ALSO - -L<err(3)|err(3)> - -=head1 HISTORY - -ERR_set_mark() and ERR_pop_to_mark() were added in OpenSSL 0.9.8. - -=cut diff --git a/openssl/doc/crypto/EVP_BytesToKey.pod b/openssl/doc/crypto/EVP_BytesToKey.pod deleted file mode 100644 index a9b6bb0..0000000 --- a/openssl/doc/crypto/EVP_BytesToKey.pod +++ /dev/null @@ -1,70 +0,0 @@ -=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 peform 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 concatentaion, 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)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> - -=head1 HISTORY - -=cut diff --git a/openssl/doc/crypto/EVP_DigestInit.pod b/openssl/doc/crypto/EVP_DigestInit.pod deleted file mode 100644 index 0895e8c..0000000 --- a/openssl/doc/crypto/EVP_DigestInit.pod +++ /dev/null @@ -1,282 +0,0 @@ -=pod - -=head1 NAME - -EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, -EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE, -EVP_MD_CTX_copy_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_sha, EVP_sha1, -EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, EVP_mdc2, -EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - -EVP digest routines - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - void EVP_MD_CTX_init(EVP_MD_CTX *ctx); - EVP_MD_CTX *EVP_MD_CTX_create(void); - - 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_cleanup(EVP_MD_CTX *ctx); - void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); - - int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); - - int EVP_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); - - #define EVP_MAX_MD_SIZE 64 /* SHA512 */ - - 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); - #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e)) - #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) - #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) - - const EVP_MD *EVP_md_null(void); - const EVP_MD *EVP_md2(void); - const EVP_MD *EVP_md5(void); - const EVP_MD *EVP_sha(void); - const EVP_MD *EVP_sha1(void); - const EVP_MD *EVP_dss(void); - const EVP_MD *EVP_dss1(void); - const EVP_MD *EVP_mdc2(void); - const EVP_MD *EVP_ripemd160(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); - #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) - #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) - -=head1 DESCRIPTION - -The EVP digest routines are a high level interface to message digests. - -EVP_MD_CTX_init() initializes digest context B<ctx>. - -EVP_MD_CTX_create() allocates, initializes and returns a digest context. - -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 functionsuch 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_cleanup() cleans up digest context B<ctx>, it should be called -after a digest context is no longer needed. - -EVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the -space allocated to it, it should be called only on a context created -using EVP_MD_CTX_create(). - -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_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(), -EVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD> -structures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2 -and RIPEMD160 digest algorithms respectively. - -EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest -algorithms but using DSS (DSA) for the signature algorithm. Note: there is -no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are -however retained for compatibility. - -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. The digest table must be initialized -using, for example, OpenSSL_add_all_digests() for these functions to work. - -=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_sha(), EVP_sha1(), EVP_dss(), -EVP_dss1(), EVP_mdc2() and EVP_ripemd160() 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. - -In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use -memory leaks will occur. - -Stack allocation of EVP_MD_CTX structures is common, for example: - - EVP_MD_CTX mctx; - EVP_MD_CTX_init(&mctx); - -This will cause binary compatibility issues if the size of EVP_MD_CTX -structure changes (this will only happen with a major release of OpenSSL). -Applications wishing to avoid this should use EVP_MD_CTX_create() instead: - - EVP_MD_CTX *mctx; - mctx = EVP_MD_CTX_create(); - - -=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; - - OpenSSL_add_all_digests(); - - 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_create(); - 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_destroy(mdctx); - - printf("Digest is: "); - for(i = 0; i < md_len; i++) - printf("%02x", md_value[i]); - printf("\n"); - - /* Call this once before exit. */ - EVP_cleanup(); - exit(0); - } - -=head1 SEE ALSO - -L<dgst(1)|dgst(1)>, -L<evp(3)|evp(3)> - -=head1 HISTORY - -EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(), -EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() -and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7. - -EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), -EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were -changed to return truly const EVP_MD * in OpenSSL 0.9.7. - -The link between digests and signing algorithms was fixed in OpenSSL 1.0 and -later, so now EVP_sha1() can be used with RSA and DSA; there is no need to -use EVP_dss1() any more. - -OpenSSL 1.0 and later does not include the MD2 digest algorithm in the -default configuration due to its security weaknesses. - -=cut diff --git a/openssl/doc/crypto/EVP_DigestSignInit.pod b/openssl/doc/crypto/EVP_DigestSignInit.pod deleted file mode 100644 index 83e6589..0000000 --- a/openssl/doc/crypto/EVP_DigestSignInit.pod +++ /dev/null @@ -1,87 +0,0 @@ -=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 initialized with -EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the -EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can -be used to set alternative signing options. - -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 -usig 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)|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)|EVP_DigestVerifyInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> - -=head1 HISTORY - -EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() -were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_DigestVerifyInit.pod b/openssl/doc/crypto/EVP_DigestVerifyInit.pod deleted file mode 100644 index 347c511..0000000 --- a/openssl/doc/crypto/EVP_DigestVerifyInit.pod +++ /dev/null @@ -1,83 +0,0 @@ -=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 initialized -with EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the -EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this -can be used to set alternative verification options. - -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 -or a negative value for failure. In particular a return value of -2 indicates -the operation is not supported by the public key algorithm. - -EVP_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)|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)|EVP_DigestSignInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> - -=head1 HISTORY - -EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() -were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_EncodeInit.pod b/openssl/doc/crypto/EVP_EncodeInit.pod deleted file mode 100644 index c6f1267..0000000 --- a/openssl/doc/crypto/EVP_EncodeInit.pod +++ /dev/null @@ -1,127 +0,0 @@ -=pod - -=head1 NAME - -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> - - void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); - void 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. - -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. - -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_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 divisbile -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_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)> - -=cut diff --git a/openssl/doc/crypto/EVP_EncryptInit.pod b/openssl/doc/crypto/EVP_EncryptInit.pod deleted file mode 100644 index d951333..0000000 --- a/openssl/doc/crypto/EVP_EncryptInit.pod +++ /dev/null @@ -1,594 +0,0 @@ -=pod - -=head1 NAME - -EVP_CIPHER_CTX_init, 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_CIPHER_CTX_cleanup, 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_idea_cbc, -EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, 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_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, -EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a); - - int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - ENGINE *impl, unsigned char *key, unsigned char *iv); - int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, 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, unsigned char *key, unsigned char *iv); - int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, 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, unsigned char *key, unsigned char *iv, int enc); - int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, 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, - unsigned char *key, 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, - unsigned char *key, 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, - unsigned char *key, 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); - int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); - - const EVP_CIPHER *EVP_get_cipherbyname(const char *name); - #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) - #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) - - #define EVP_CIPHER_nid(e) ((e)->nid) - #define EVP_CIPHER_block_size(e) ((e)->block_size) - #define EVP_CIPHER_key_length(e) ((e)->key_len) - #define EVP_CIPHER_iv_length(e) ((e)->iv_len) - #define EVP_CIPHER_flags(e) ((e)->flags) - #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE) - int EVP_CIPHER_type(const EVP_CIPHER *ctx); - - #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) - #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) - #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) - #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len) - #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) - #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data) - #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d)) - #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) - #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags) - #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE) - - 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_init() initializes cipher contex B<ctx>. - -EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption -with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized -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>. - -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 L<standard block padding|/NOTES> (aka PKCS padding). 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_cleanup() clears all information from a cipher context -and free up any allocated memory associate with it. It should be called -after all operations using a cipher are complete so sensitive information -does not remain in memory. - -EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a -similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and -EVP_CipherInit_ex() except the B<ctx> 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. 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_IV_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_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_cleanup() 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 1 for -success or zero for failure. - -=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_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void) - -DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void) - -Two key triple DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void) - -Three key triple DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_desx_cbc(void) - -DESX algorithm in CBC mode. - -=item EVP_rc4(void) - -RC4 stream cipher. This is a variable key length cipher with default key length 128 bits. - -=item EVP_rc4_40(void) - -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(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void) - -IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void) - -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(void), EVP_rc2_64_cbc(void) - -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(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void); - -Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key -length cipher. - -=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void) - -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(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void) - -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(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void) - -AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively. -These ciphers require additional control operations to function correctly: see -L<GCM mode> section below for details. - -=item EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void) - -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. - -=back - -=head1 GCM Mode - -For GCM mode ciphers the behaviour of the EVP interface is subtly altered and -several GCM specific 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 GCM mode: - - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL); - -Sets the GCM IV length: this call can only be made before specifying an IV. If -not called a default IV length is used (96 bits for AES). - - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_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). - - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag); - -Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal -when decrypting data and must be made B<before> any data is processed (e.g. -before any EVP_DecryptUpdate() call). - -See L<EXAMPLES> below for an example of the use of GCM mode. - -=head1 CCM Mode - -The behaviour of CCM mode ciphers is similar to CCM mode but with a few -additional requirements and different ctrl values. - -Like GCM mode 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_CCM_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_CCM_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. - -=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; - - EVP_CIPHER_CTX_init(&ctx); - 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_cleanup(&ctx); - /* Need binary mode for fopen because encrypted data is - * binary data. Also cannot use strlen() on it because - * it wont 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 */ - EVP_CIPHER_CTX_init(&ctx); - 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_cleanup(&ctx); - return 0; - } - fwrite(outbuf, 1, outlen, out); - } - if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) - { - /* Error */ - EVP_CIPHER_CTX_cleanup(&ctx); - return 0; - } - fwrite(outbuf, 1, outlen, out); - - EVP_CIPHER_CTX_cleanup(&ctx); - return 1; - } - - -=head1 SEE ALSO - -L<evp(3)|evp(3)> - -=head1 HISTORY - -EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), -EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), -EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in -OpenSSL 0.9.7. - -IDEA appeared in OpenSSL 0.9.7 but was often disabled due to -patent concerns; the last patents expired in 2012. - -=cut diff --git a/openssl/doc/crypto/EVP_OpenInit.pod b/openssl/doc/crypto/EVP_OpenInit.pod deleted file mode 100644 index 2e710da..0000000 --- a/openssl/doc/crypto/EVP_OpenInit.pod +++ /dev/null @@ -1,63 +0,0 @@ -=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)|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)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_SealInit(3)|EVP_SealInit(3)> - -=head1 HISTORY - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod b/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod deleted file mode 100644 index 44b5fdb..0000000 --- a/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod +++ /dev/null @@ -1,134 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_get_default_digest_nid, -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 - 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); - - int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); - - #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); - -=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 genration 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. - -=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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> -L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_CTX_new.pod b/openssl/doc/crypto/EVP_PKEY_CTX_new.pod deleted file mode 100644 index a9af867..0000000 --- a/openssl/doc/crypto/EVP_PKEY_CTX_new.pod +++ /dev/null @@ -1,52 +0,0 @@ -=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 genration for some algorithms. - -EVP_PKEY_CTX_dup() duplicates the context B<ctx>. - -EVP_PKEY_CTX_free() frees up the context B<ctx>. - -=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)|EVP_PKEY_new(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_cmp.pod b/openssl/doc/crypto/EVP_PKEY_cmp.pod deleted file mode 100644 index f8e7ff1..0000000 --- a/openssl/doc/crypto/EVP_PKEY_cmp.pod +++ /dev/null @@ -1,63 +0,0 @@ -=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 paramters -(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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_decrypt.pod b/openssl/doc/crypto/EVP_PKEY_decrypt.pod deleted file mode 100644 index 8479832..0000000 --- a/openssl/doc/crypto/EVP_PKEY_decrypt.pod +++ /dev/null @@ -1,93 +0,0 @@ -=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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_derive.pod b/openssl/doc/crypto/EVP_PKEY_derive.pod deleted file mode 100644 index 27464be..0000000 --- a/openssl/doc/crypto/EVP_PKEY_derive.pod +++ /dev/null @@ -1,93 +0,0 @@ -=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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_encrypt.pod b/openssl/doc/crypto/EVP_PKEY_encrypt.pod deleted file mode 100644 index 6799ce1..0000000 --- a/openssl/doc/crypto/EVP_PKEY_encrypt.pod +++ /dev/null @@ -1,99 +0,0 @@ -=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)|pem(3)> or -L<d2i_X509(3)|d2i_X509(3)> for means to load a public key. You may also simply -set 'eng = NULL;' to start with the default OpenSSL RSA implementation: - - #include <openssl/evp.h> - #include <openssl/rsa.h> - #include <openssl/engine.h> - - EVP_PKEY_CTX *ctx; - ENGINE *eng; - unsigned char *out, *in; - size_t outlen, inlen; - EVP_PKEY *key; - /* NB: assumes 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)|d2i_X509(3)>, -L<engine(3)|engine(3)>, -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_get_default_digest.pod b/openssl/doc/crypto/EVP_PKEY_get_default_digest.pod deleted file mode 100644 index 8ff597d..0000000 --- a/openssl/doc/crypto/EVP_PKEY_get_default_digest.pod +++ /dev/null @@ -1,41 +0,0 @@ -=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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, - -=head1 HISTORY - -This function was first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_keygen.pod b/openssl/doc/crypto/EVP_PKEY_keygen.pod deleted file mode 100644 index fd431ac..0000000 --- a/openssl/doc/crypto/EVP_PKEY_keygen.pod +++ /dev/null @@ -1,161 +0,0 @@ -=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_PKEVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data - 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 genration 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 genration 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 specifiic 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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_new.pod b/openssl/doc/crypto/EVP_PKEY_new.pod deleted file mode 100644 index 10687e4..0000000 --- a/openssl/doc/crypto/EVP_PKEY_new.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_new, EVP_PKEY_free - private key allocation functions. - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - EVP_PKEY *EVP_PKEY_new(void); - 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. - -EVP_PKEY_free() frees up the private key B<key>. - -=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)|EVP_PKEY_set1_RSA(3)> should be used. - -=head1 RETURN VALUES - -EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> -structure of B<NULL> if an error occurred. - -EVP_PKEY_free() does not return a value. - -=head1 SEE ALSO - -L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_print_private.pod b/openssl/doc/crypto/EVP_PKEY_print_private.pod deleted file mode 100644 index ce9d70d..0000000 --- a/openssl/doc/crypto/EVP_PKEY_print_private.pod +++ /dev/null @@ -1,53 +0,0 @@ -=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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod b/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod deleted file mode 100644 index 6f10175..0000000 --- a/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod +++ /dev/null @@ -1,80 +0,0 @@ -=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_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, -EVP_PKEY_type - 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); - - 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_type(int type); - -=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_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_type() returns the type of key corresponding to the value -B<type>. The type of a key can be obtained with -EVP_PKEY_type(pkey->type). The return value will be EVP_PKEY_RSA, -EVP_PKEY_DSA, EVP_PKEY_DH or EVP_PKEY_EC for the corresponding -key types or NID_undef if the key type is unassigned. - -=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. - -=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. - -=head1 SEE ALSO - -L<EVP_PKEY_new(3)|EVP_PKEY_new(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_sign.pod b/openssl/doc/crypto/EVP_PKEY_sign.pod deleted file mode 100644 index 21974b4..0000000 --- a/openssl/doc/crypto/EVP_PKEY_sign.pod +++ /dev/null @@ -1,106 +0,0 @@ -=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)|EVP_DigestSignInit(3)> and -L<EVP_SignInit(3)|EVP_SignInit(3)> signing interfaces instead. - -After the call to EVP_PKEY_sign_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation (see L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>). - -The function EVP_PKEY_sign() can be called more than once on the same -context if several operations are performed using the same parameters. - -=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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_verify.pod b/openssl/doc/crypto/EVP_PKEY_verify.pod deleted file mode 100644 index 90612ba..0000000 --- a/openssl/doc/crypto/EVP_PKEY_verify.pod +++ /dev/null @@ -1,91 +0,0 @@ -=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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_PKEY_verify_recover.pod b/openssl/doc/crypto/EVP_PKEY_verify_recover.pod deleted file mode 100644 index 23a28a9..0000000 --- a/openssl/doc/crypto/EVP_PKEY_verify_recover.pod +++ /dev/null @@ -1,103 +0,0 @@ -=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)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/EVP_SealInit.pod b/openssl/doc/crypto/EVP_SealInit.pod deleted file mode 100644 index 19112a5..0000000 --- a/openssl/doc/crypto/EVP_SealInit.pod +++ /dev/null @@ -1,85 +0,0 @@ -=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)|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)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_OpenInit(3)|EVP_OpenInit(3)> - -=head1 HISTORY - -EVP_SealFinal() did not return a value before OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/EVP_SignInit.pod b/openssl/doc/crypto/EVP_SignInit.pod deleted file mode 100644 index c63d6b3..0000000 --- a/openssl/doc/crypto/EVP_SignInit.pod +++ /dev/null @@ -1,107 +0,0 @@ -=pod - -=head1 NAME - -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 initialized with -EVP_MD_CTX_init() 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 paramter, and not used as an IN parameter. -The number of bytes of data written (i.e. the length of the signature) -will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes -will be written. - -EVP_SignInit() initializes a signing context B<ctx> to use the default -implementation of digest B<type>. - -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)|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. - -Due to the link between message digests and public key algorithms the correct -digest algorithm must be used with the correct public key type. A list of -algorithms and associated public key algorithms appears in -L<EVP_DigestInit(3)|EVP_DigestInit(3)>. - -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)|EVP_VerifyInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> - -=head1 HISTORY - -EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_SignInit_ex() was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/EVP_VerifyInit.pod b/openssl/doc/crypto/EVP_VerifyInit.pod deleted file mode 100644 index 9097f09..0000000 --- a/openssl/doc/crypto/EVP_VerifyInit.pod +++ /dev/null @@ -1,95 +0,0 @@ -=pod - -=head1 NAME - -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 initialized by calling -EVP_MD_CTX_init() 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)|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. - -Due to the link between message digests and public key algorithms the correct -digest algorithm must be used with the correct public key type. A list of -algorithms and associated public key algorithms appears in -L<EVP_DigestInit(3)|EVP_DigestInit(3)>. - -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(3)|evp(3)>, -L<EVP_SignInit(3)|EVP_SignInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> - -=head1 HISTORY - -EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_VerifyInit_ex() was added in OpenSSL 0.9.7 - -=cut diff --git a/openssl/doc/crypto/OBJ_nid2obj.pod b/openssl/doc/crypto/OBJ_nid2obj.pod deleted file mode 100644 index b8d2896..0000000 --- a/openssl/doc/crypto/OBJ_nid2obj.pod +++ /dev/null @@ -1,170 +0,0 @@ -=pod - -=head1 NAME - -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 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); - void OBJ_cleanup(void); - -=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 respresentation 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. - -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_cleanup() cleans up OpenSSLs internal object table: this should -be called before an application exits if any new objects were added -using OBJ_create(). - -=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. -It returns a pointer to an internal table and does not -allocate memory; ASN1_OBJECT_free() will have no effect. - -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)|ERR_get_error(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/OPENSSL_Applink.pod b/openssl/doc/crypto/OPENSSL_Applink.pod deleted file mode 100644 index e54de12..0000000 --- a/openssl/doc/crypto/OPENSSL_Applink.pod +++ /dev/null @@ -1,21 +0,0 @@ -=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 <openssl>/ms/applink.c. - -=cut diff --git a/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod deleted file mode 100644 index f7ca7cb..0000000 --- a/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number - -=head1 SYNOPSIS - - #include <openssl/opensslv.h> - #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL - - #include <openssl/crypto.h> - long SSLeay(void); - const char *SSLeay_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. - - -For backward compatibility, SSLEAY_VERSION_NUMBER is also defined. - -SSLeay() returns this number. The return value can be compared to the -macro to make sure that the correct version of the library has been -loaded, especially when using DLLs on Windows systems. - -SSLeay_version() returns different strings depending on B<t>: - -=over 4 - -=item SSLEAY_VERSION - -The text variant of the version number and the release date. For example, -"OpenSSL 0.9.5a 1 Apr 2000". - -=item SSLEAY_CFLAGS - -The compiler flags set for the compilation process in the form -"compiler: ..." if available or "compiler: information not available" -otherwise. - -=item SSLEAY_BUILT_ON - -The date of the build process in the form "built on: ..." if available -or "built on: date not available" otherwise. - -=item SSLEAY_PLATFORM - -The "Configure" target of the library build in the form "platform: ..." -if available or "platform: information not available" otherwise. - -=item SSLEAY_DIR - -The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "..."" -if available or "OPENSSLDIR: 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)|crypto(3)> - -=head1 HISTORY - -SSLeay() and SSLEAY_VERSION_NUMBER are available in all versions of SSLeay and OpenSSL. -OPENSSL_VERSION_NUMBER is available in all versions of OpenSSL. -B<SSLEAY_DIR> was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/OPENSSL_config.pod b/openssl/doc/crypto/OPENSSL_config.pod deleted file mode 100644 index 4e71365..0000000 --- a/openssl/doc/crypto/OPENSSL_config.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions - -=head1 SYNOPSIS - - #include <openssl/conf.h> - - void OPENSSL_config(const char *appname); - void OPENSSL_no_config(void); - -=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. - -=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 new ENGINE functionality was added to OpenSSL 0.9.7. -In OpenSSL 0.9.7 control functions can be supported by ENGINEs, this can be -used (among other things) 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. - -Applications should free up configuration at application closedown by calling -CONF_modules_free(). - -=head1 RETURN VALUES - -Neither OPENSSL_config() nor OPENSSL_no_config() return a value. - -=head1 SEE ALSO - -L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>, -L<CONF_modules_free(3)|CONF_modules_free(3)> - -=head1 HISTORY - -OPENSSL_config() and OPENSSL_no_config() first appeared in OpenSSL 0.9.7 - -=cut diff --git a/openssl/doc/crypto/OPENSSL_ia32cap.pod b/openssl/doc/crypto/OPENSSL_ia32cap.pod deleted file mode 100644 index 5bcb82e..0000000 --- a/openssl/doc/crypto/OPENSSL_ia32cap.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_ia32cap, OPENSSL_ia32cap_loc - the IA-32 processor capabilities vector - -=head1 SYNOPSIS - - unsigned long *OPENSSL_ia32cap_loc(void); - #define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0]) - -=head1 DESCRIPTION - -Value returned by OPENSSL_ia32cap_loc() is address of a variable -containing IA-32 processor capabilities bit vector as it appears in -EDX:ECX register pair after executing CPUID instruction with EAX=1 -input value (see Intel Application Note #241618). Naturally it's -meaningful on x86 and x86_64 platforms only. The variable is normally -set up automatically upon toolkit initialization, but can be -manipulated afterwards to modify crypto library behaviour. For the -moment of this writing following bits are significant: - -=over - -=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 #57 denoting AES-NI instruction set extension; - -=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, 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. Even though you can manipulate the value programmatically, -you most likely will find it more appropriate to set up an environment -variable with the same name prior starting target application, e.g. on -Intel P4 processor 'env OPENSSL_ia32cap=0x16980010 apps/openssl', or -better yet 'env OPENSSL_ia32cap=~0x1000000 apps/openssl' to achieve same -effect without modifying the application source code. Alternatively you -can reconfigure the toolkit with no-sse2 option and recompile. - -Less intuitive is clearing bit #28. 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 vector is further extended with EBX value returned by CPUID with -EAX=7 and ECX=0 as input. Following bits are significant: - -=over - -=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. MUXL -and RORX; - -=item bit #64+18 denoting availability of RDSEED instruction; - -=item bit #64+19 denoting availability of ADCX and ADOX instructions; - -=back diff --git a/openssl/doc/crypto/OPENSSL_instrument_bus.pod b/openssl/doc/crypto/OPENSSL_instrument_bus.pod deleted file mode 100644 index 4ed83e4..0000000 --- a/openssl/doc/crypto/OPENSSL_instrument_bus.pod +++ /dev/null @@ -1,42 +0,0 @@ -=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. diff --git a/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod b/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod deleted file mode 100644 index de62912..0000000 --- a/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod +++ /dev/null @@ -1,51 +0,0 @@ -=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)|conf(3)>, L<OPENSSL_config(3)|OPENSSL_config(3)> - -=head1 HISTORY - -These functions first appeared in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod b/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod deleted file mode 100644 index bcb79e5..0000000 --- a/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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> - - void OpenSSL_add_all_algorithms(void); - void OpenSSL_add_all_ciphers(void); - void OpenSSL_add_all_digests(void); - - void EVP_cleanup(void); - -=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(). - -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. - -EVP_cleanup() removes all ciphers and digests from the table. - -=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)|evp(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> - -=cut diff --git a/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod b/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod deleted file mode 100644 index e070c45..0000000 --- a/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - - PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format. - -=head1 SYNOPSIS - - #include <openssl/cms.h> - #include <openssl/pem.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)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> -L<CMS_decrypt(3)|CMS_decrypt(3)>, -L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>, -L<i2d_CMS_bio_stream(3)|i2d_CMS_bio_stream(3)> - -=head1 HISTORY - -PEM_write_bio_CMS_stream() was added to OpenSSL 1.0.0 - -=cut diff --git a/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod b/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod deleted file mode 100644 index 16fc9b6..0000000 --- a/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format. - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - #include <openssl/pem.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)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, -L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, -L<i2d_PKCS7_bio_stream(3)|i2d_PKCS7_bio_stream(3)> - -=head1 HISTORY - -PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0 - -=cut diff --git a/openssl/doc/crypto/PKCS12_create.pod b/openssl/doc/crypto/PKCS12_create.pod deleted file mode 100644 index de7cab2..0000000 --- a/openssl/doc/crypto/PKCS12_create.pod +++ /dev/null @@ -1,75 +0,0 @@ -=pod - -=head1 NAME - -PKCS12_create - create a PKCS#12 structure - -=head1 SYNOPSIS - - #include <openssl/pkcs12.h> - - PKCS12 *PKCS12_create(char *pass, 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 certifictate 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. - -=head1 NEW FUNCTIONALITY IN OPENSSL 0.9.8 - -Some additional functionality was added to PKCS12_create() in OpenSSL -0.9.8. These extensions are detailed below. - -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 -certficate 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)|d2i_PKCS12(3)> - -=head1 HISTORY - -PKCS12_create was added in OpenSSL 0.9.3 - -=cut diff --git a/openssl/doc/crypto/PKCS12_parse.pod b/openssl/doc/crypto/PKCS12_parse.pod deleted file mode 100644 index c54cf2a..0000000 --- a/openssl/doc/crypto/PKCS12_parse.pod +++ /dev/null @@ -1,57 +0,0 @@ -=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. - -=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)|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)|d2i_PKCS12(3)> - -=head1 HISTORY - -PKCS12_parse was added in OpenSSL 0.9.3 - -=cut diff --git a/openssl/doc/crypto/PKCS7_decrypt.pod b/openssl/doc/crypto/PKCS7_decrypt.pod deleted file mode 100644 index 325699d..0000000 --- a/openssl/doc/crypto/PKCS7_decrypt.pod +++ /dev/null @@ -1,55 +0,0 @@ -=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 - -OpenSSL_add_all_algorithms() (or equivalent) should be called before using this -function or errors about unknown algorithms will occur. - -Although the recipients certificate is not needed to decrypt the data it is needed -to locate the appropriate (of possible several) recipients in the 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)|ERR_get_error(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> - -=head1 HISTORY - -PKCS7_decrypt() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/doc/crypto/PKCS7_encrypt.pod b/openssl/doc/crypto/PKCS7_encrypt.pod deleted file mode 100644 index 2cd925a..0000000 --- a/openssl/doc/crypto/PKCS7_encrypt.pod +++ /dev/null @@ -1,80 +0,0 @@ -=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)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -PKCS7_decrypt() was added to OpenSSL 0.9.5 -The B<PKCS7_STREAM> flag was first supported in OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/PKCS7_sign.pod b/openssl/doc/crypto/PKCS7_sign.pod deleted file mode 100644 index 64a3514..0000000 --- a/openssl/doc/crypto/PKCS7_sign.pod +++ /dev/null @@ -1,116 +0,0 @@ -=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 corresponsding 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 autenticatedAttributes -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. - -In OpenSSL 1.0.0 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 B<PKCS7_sign_add_signer()>. B<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. - -In OpenSSL 1.0.0 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)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> - -=head1 HISTORY - -PKCS7_sign() was added to OpenSSL 0.9.5 - -The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0 - -The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0 - -=cut diff --git a/openssl/doc/crypto/PKCS7_sign_add_signer.pod b/openssl/doc/crypto/PKCS7_sign_add_signer.pod deleted file mode 100644 index ebec4d5..0000000 --- a/openssl/doc/crypto/PKCS7_sign_add_signer.pod +++ /dev/null @@ -1,87 +0,0 @@ -=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 struture: 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 autenticatedAttributes -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)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_final(3)|PKCS7_final(3)>, - -=head1 HISTORY - -PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0 - -=cut diff --git a/openssl/doc/crypto/PKCS7_verify.pod b/openssl/doc/crypto/PKCS7_verify.pod deleted file mode 100644 index f083306..0000000 --- a/openssl/doc/crypto/PKCS7_verify.pod +++ /dev/null @@ -1,118 +0,0 @@ -=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 certficate 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>. - -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)|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)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)> - -=head1 HISTORY - -PKCS7_verify() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/doc/crypto/RAND_add.pod b/openssl/doc/crypto/RAND_add.pod deleted file mode 100644 index 67c66f3..0000000 --- a/openssl/doc/crypto/RAND_add.pod +++ /dev/null @@ -1,77 +0,0 @@ -=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); - - int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); - void RAND_screen(void); - -=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)|RAND_egd(3)> -or L<RAND_load_file(3)|RAND_load_file(3)>. - -RAND_seed() is equivalent to RAND_add() when B<num == entropy>. - -RAND_event() collects the entropy from Windows events such as mouse -movements and other user interaction. It should be called with the -B<iMsg>, B<wParam> and B<lParam> arguments of I<all> messages sent to -the window procedure. It will estimate the entropy contained in the -event message (if any), and add it to the PRNG. The program can then -process the messages as usual. - -The RAND_screen() function is available for the convenience of Windows -programmers. It adds the current contents of the screen to the PRNG. -For applications that can catch Windows events, seeding the PRNG by -calling RAND_event() is a significantly better source of -randomness. It should be noted that both methods cannot be used on -servers that run without user interaction. - -=head1 RETURN VALUES - -RAND_status() and RAND_event() return 1 if the PRNG has been seeded -with enough data, 0 otherwise. - -The other functions do not return values. - -=head1 SEE ALSO - -L<rand(3)|rand(3)>, L<RAND_egd(3)|RAND_egd(3)>, -L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> - -=head1 HISTORY - -RAND_seed() and RAND_screen() are available in all versions of SSLeay -and OpenSSL. RAND_add() and RAND_status() have been added in OpenSSL -0.9.5, RAND_event() in OpenSSL 0.9.5a. - -=cut diff --git a/openssl/doc/crypto/RAND_bytes.pod b/openssl/doc/crypto/RAND_bytes.pod deleted file mode 100644 index 1a9b91e..0000000 --- a/openssl/doc/crypto/RAND_bytes.pod +++ /dev/null @@ -1,50 +0,0 @@ -=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); - - int RAND_pseudo_bytes(unsigned char *buf, int num); - -=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() 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)|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)|rand(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<RAND_add(3)|RAND_add(3)> - -=head1 HISTORY - -RAND_bytes() is available in all versions of SSLeay and OpenSSL. It -has a return value since OpenSSL 0.9.5. RAND_pseudo_bytes() was added -in OpenSSL 0.9.5. - -=cut diff --git a/openssl/doc/crypto/RAND_cleanup.pod b/openssl/doc/crypto/RAND_cleanup.pod deleted file mode 100644 index 3a8f074..0000000 --- a/openssl/doc/crypto/RAND_cleanup.pod +++ /dev/null @@ -1,29 +0,0 @@ -=pod - -=head1 NAME - -RAND_cleanup - erase the PRNG state - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - void RAND_cleanup(void); - -=head1 DESCRIPTION - -RAND_cleanup() erases the memory used by the PRNG. - -=head1 RETURN VALUE - -RAND_cleanup() returns no value. - -=head1 SEE ALSO - -L<rand(3)|rand(3)> - -=head1 HISTORY - -RAND_cleanup() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/RAND_egd.pod b/openssl/doc/crypto/RAND_egd.pod deleted file mode 100644 index 80fa734..0000000 --- a/openssl/doc/crypto/RAND_egd.pod +++ /dev/null @@ -1,88 +0,0 @@ -=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)|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)|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)|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)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, -L<RAND_cleanup(3)|RAND_cleanup(3)> - -=head1 HISTORY - -RAND_egd() is available since OpenSSL 0.9.5. - -RAND_egd_bytes() is available since OpenSSL 0.9.6. - -RAND_query_egd_bytes() is available since OpenSSL 0.9.7. - -The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/RAND_load_file.pod b/openssl/doc/crypto/RAND_load_file.pod deleted file mode 100644 index d8c134e..0000000 --- a/openssl/doc/crypto/RAND_load_file.pod +++ /dev/null @@ -1,53 +0,0 @@ -=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. The seed file is $RANDFILE if that environment variable is -set, $HOME/.rnd otherwise. If $HOME 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 to B<max_bytes> are read; starting with OpenSSL 0.9.5, -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. - -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)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> - -=head1 HISTORY - -RAND_load_file(), RAND_write_file() and RAND_file_name() are available in -all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/RAND_set_rand_method.pod b/openssl/doc/crypto/RAND_set_rand_method.pod deleted file mode 100644 index e5b780f..0000000 --- a/openssl/doc/crypto/RAND_set_rand_method.pod +++ /dev/null @@ -1,83 +0,0 @@ -=pod - -=head1 NAME - -RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - 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_SSLeay(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_SSLeay(). - -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 the implementation of RAND_seed(), -RAND_bytes(), 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_SSLeay() return pointers to the respective methods. - -=head1 NOTES - -As of version 0.9.7, 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)|rand(3)>, L<engine(3)|engine(3)> - -=head1 HISTORY - -RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are -available in all versions of OpenSSL. - -In the engine version of version 0.9.6, RAND_set_rand_method() was altered to -take an ENGINE pointer as its argument. As of version 0.9.7, that has been -reverted as the ENGINE API transparently overrides RAND defaults if used, -otherwise RAND API functions work as before. RAND_set_rand_engine() was also -introduced in version 0.9.7. - -=cut diff --git a/openssl/doc/crypto/RSA_blinding_on.pod b/openssl/doc/crypto/RSA_blinding_on.pod deleted file mode 100644 index fd2c69a..0000000 --- a/openssl/doc/crypto/RSA_blinding_on.pod +++ /dev/null @@ -1,43 +0,0 @@ -=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 SEE ALSO - -L<rsa(3)|rsa(3)>, L<rand(3)|rand(3)> - -=head1 HISTORY - -RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/RSA_check_key.pod b/openssl/doc/crypto/RSA_check_key.pod deleted file mode 100644 index a5198f3..0000000 --- a/openssl/doc/crypto/RSA_check_key.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -RSA_check_key - validate private RSA keys - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_check_key(RSA *rsa); - -=head1 DESCRIPTION - -This function validates RSA keys. It checks that B<p> and B<q> are -in fact prime, and that B<n = p*q>. - -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>. - -As such, this function can not be used with any arbitrary RSA key object, -even if it is otherwise fit for regular RSA operation. See B<NOTES> for more -information. - -=head1 RETURN VALUE - -RSA_check_key() returns 1 if B<rsa> is a valid RSA key, and 0 otherwise. --1 is returned 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)|ERR_get_error(3)>. - -=head1 NOTES - -This function does not work on RSA public keys that have only the modulus -and public exponent elements populated. It performs integrity checks on all -the RSA key material, so the RSA key structure must contain all the private -key data too. - -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<rsa(3)|rsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -RSA_check_key() appeared in OpenSSL 0.9.4. - -=cut diff --git a/openssl/doc/crypto/RSA_generate_key.pod b/openssl/doc/crypto/RSA_generate_key.pod deleted file mode 100644 index 0882a1a..0000000 --- a/openssl/doc/crypto/RSA_generate_key.pod +++ /dev/null @@ -1,80 +0,0 @@ -=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: - - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); - -=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)|BN_generate_prime(3)> page. - -=over 4 - -=item * - -While a random prime number is generated, it is called as -described in L<BN_generate_prime(3)|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)|BN_generate_prime(3)> for further details. - -=head1 RETURN VALUE - -If key generation fails, RSA_generate_key() returns B<NULL>. - -The error codes can be obtained by L<ERR_get_error(3)|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)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<RSA_free(3)|RSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)> - -=head1 HISTORY - -The B<cb_arg> argument was added in SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/RSA_get_ex_new_index.pod b/openssl/doc/crypto/RSA_get_ex_new_index.pod deleted file mode 100644 index 7d0fd1f..0000000 --- a/openssl/doc/crypto/RSA_get_ex_new_index.pod +++ /dev/null @@ -1,120 +0,0 @@ -=pod - -=head1 NAME - -RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int RSA_set_ex_data(RSA *r, int idx, void *arg); - - void *RSA_get_ex_data(RSA *r, int idx); - - typedef int 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, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -This has several potential uses, it can be used to cache data associated with -a structure (for example the hash of some part of the structure) or some -additional data (for example a handle to the data in an external library). - -Since the application data can be anything at all it is passed and retrieved -as a B<void *> type. - -The B<RSA_get_ex_new_index()> function is initially called to "register" some -new application specific data. It takes three optional function pointers which -are called when the parent structure (in this case an RSA structure) is -initially created, when it is copied and when it is freed up. If any or all of -these function pointer arguments are not used they should be set to NULL. The -precise manner in which these function pointers are called is described in more -detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer -parameters which will be passed to the supplied functions but which otherwise -have no special meaning. It returns an B<index> which should be stored -(typically in a static variable) and passed used in the B<idx> parameter in -the remaining functions. Each successful call to B<RSA_get_ex_new_index()> -will return an index greater than any previously returned, this is important -because the optional functions are called in order of increasing index value. - -B<RSA_set_ex_data()> is used to set application specific data, the data is -supplied in the B<arg> parameter and its precise meaning is up to the -application. - -B<RSA_get_ex_data()> is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous B<RSA_set_ex_data()> call. - -B<new_func()> is called when a structure is initially allocated (for example -with B<RSA_new()>. The parent structure members will not have any meaningful -values at this point. This function will typically be used to allocate any -application specific structure. - -B<free_func()> is called when a structure is being freed up. The dynamic parent -structure members should not be accessed because they will be freed up when -this function is called. - -B<new_func()> and B<free_func()> take the same parameters. B<parent> is a -pointer to the parent RSA structure. B<ptr> is a the application specific data -(this wont be of much use in B<new_func()>. B<ad> is a pointer to the -B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions -B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate -it. The B<idx> parameter is the index: this will be the same value returned by -B<RSA_get_ex_new_index()> when the functions were initially registered. Finally -the B<argl> and B<argp> parameters are the values originally passed to the same -corresponding parameters when B<RSA_get_ex_new_index()> was called. - -B<dup_func()> is called when a structure is being copied. Pointers to the -destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and -B<from> parameters respectively. The B<from_d> parameter is passed a pointer to -the source application data when the function is called, when the function returns -the value is copied to the destination: the application can thus modify the data -pointed to by B<from_d> and have different values in the source and destination. -The B<idx>, B<argl> and B<argp> parameters are the same as those in B<new_func()> -and B<free_func()>. - -=head1 RETURN VALUES - -B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a valid -index value). - -B<RSA_set_ex_data()> returns 1 on success or 0 on failure. - -B<RSA_get_ex_data()> returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid B<idx> -parameter. - -B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success. - -On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 BUGS - -B<dup_func()> is currently never called. - -The return value of B<new_func()> is ignored. - -The B<new_func()> function isn't very useful because no meaningful values are -present in the parent RSA structure when it is called. - -=head1 SEE ALSO - -L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> - -=head1 HISTORY - -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are -available since SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/RSA_new.pod b/openssl/doc/crypto/RSA_new.pod deleted file mode 100644 index 3d15b92..0000000 --- a/openssl/doc/crypto/RSA_new.pod +++ /dev/null @@ -1,41 +0,0 @@ -=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. - -=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)|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)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, -L<RSA_generate_key(3)|RSA_generate_key(3)>, -L<RSA_new_method(3)|RSA_new_method(3)> - -=head1 HISTORY - -RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod b/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod deleted file mode 100644 index b8f678f..0000000 --- a/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod +++ /dev/null @@ -1,124 +0,0 @@ -=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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, -L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> - -=head1 HISTORY - -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_SSLv23(), RSA_padding_check_SSLv23(), -RSA_padding_add_none() and RSA_padding_check_none() appeared in -SSLeay 0.9.0. - -RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were -added in OpenSSL 0.9.2b. - -=cut diff --git a/openssl/doc/crypto/RSA_print.pod b/openssl/doc/crypto/RSA_print.pod deleted file mode 100644 index c971e91..0000000 --- a/openssl/doc/crypto/RSA_print.pod +++ /dev/null @@ -1,49 +0,0 @@ -=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<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> - -=head1 HISTORY - -RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), -DH_print_fp() are available in all versions of SSLeay and OpenSSL. -DSAparams_print() and DSAparams_print_fp() were added in SSLeay 0.8. - -=cut diff --git a/openssl/doc/crypto/RSA_private_encrypt.pod b/openssl/doc/crypto/RSA_private_encrypt.pod deleted file mode 100644 index 746a80c..0000000 --- a/openssl/doc/crypto/RSA_private_encrypt.pod +++ /dev/null @@ -1,70 +0,0 @@ -=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, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - - int RSA_public_decrypt(int flen, 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)|RSA_sign(3)> and L<RSA_verify(3)|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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> - -=head1 HISTORY - -The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is -available since SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/RSA_public_encrypt.pod b/openssl/doc/crypto/RSA_public_encrypt.pod deleted file mode 100644 index ab0fe3b..0000000 --- a/openssl/doc/crypto/RSA_public_encrypt.pod +++ /dev/null @@ -1,84 +0,0 @@ -=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, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - - int RSA_private_decrypt(int flen, 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)|ERR_get_error(3)>. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<RSA_size(3)|RSA_size(3)> - -=head1 HISTORY - -The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is -available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b. - -=cut diff --git a/openssl/doc/crypto/RSA_set_method.pod b/openssl/doc/crypto/RSA_set_method.pod deleted file mode 100644 index 0ef0781..0000000 --- a/openssl/doc/crypto/RSA_set_method.pod +++ /dev/null @@ -1,206 +0,0 @@ -=pod - -=head1 NAME - -RSA_set_default_method, RSA_get_default_method, RSA_set_method, -RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, 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_SSLeay(void); - - RSA_METHOD *RSA_null_method(void); - - int RSA_flags(const RSA *rsa); - - RSA *RSA_new_method(RSA_METHOD *method); - -=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_SSLeay(). - -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. - -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_FLAG_SIGN_VER - enable rsa_sign and rsa_verify - * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match - */ - int flags; - - char *app_data; /* ?? */ - - /* sign. For backward compatibility, this is used only - * if (flags & RSA_FLAG_SIGN_VER) - */ - int (*rsa_sign)(int type, - const unsigned char *m, unsigned int m_length, - unsigned char *sigret, unsigned int *siglen, const RSA *rsa); - /* verify. For backward compatibility, this is used only - * if (flags & RSA_FLAG_SIGN_VER) - */ - int (*rsa_verify)(int 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_SSLeay(), 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)|ERR_get_error(3)> if the allocation fails. Otherwise -it returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, RSA_METHOD implementations are grouped together with -other algorithmic APIs (eg. DSA_METHOD, EVP_CIPHER, etc) into B<ENGINE> -modules. If a default ENGINE is specified for RSA functionality using an -ENGINE API function, that will override any RSA defaults set using the RSA -API (ie. RSA_set_default_method()). For this reason, the ENGINE API is the -recommended way to control default implementations for use in RSA and other -cryptographic algorithms. - -=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(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)> - -=head1 HISTORY - -RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8. -RSA_get_default_method(), RSA_set_method() and RSA_get_method() as -well as the rsa_sign and rsa_verify components of RSA_METHOD were -added in OpenSSL 0.9.4. - -RSA_set_default_openssl_method() and RSA_get_default_openssl_method() -replaced RSA_set_default_method() and RSA_get_default_method() -respectively, and RSA_set_method() and RSA_new_method() were altered to use -B<ENGINE>s rather than B<RSA_METHOD>s during development of the engine -version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE -API was restructured so that this change was reversed, and behaviour of the -other functions resembled more closely the previous behaviour. The -behaviour of defaults in the ENGINE API now transparently overrides the -behaviour of defaults in the RSA API without requiring changing these -function prototypes. - -=cut diff --git a/openssl/doc/crypto/RSA_sign.pod b/openssl/doc/crypto/RSA_sign.pod deleted file mode 100644 index fc16b1f..0000000 --- a/openssl/doc/crypto/RSA_sign.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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> as specified in PKCS #1 v2.0. It stores the -signature in B<sigret> and the signature size in B<siglen>. B<sigret> -must point to RSA_size(B<rsa>) bytes of memory. -Note that PKCS #1 adds meta-data, placing limits on the size of the -key that can be used. -See L<RSA_private_encrypt(3)|RSA_private_encrypt(3)> for lower-level -operations. - -B<type> denotes the message digest algorithm that was used to generate -B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>; -see L<objects(3)|objects(3)> for details. 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, 0 otherwise. RSA_verify() returns 1 -on successful verification, 0 otherwise. - -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 BUGS - -Certain signatures with an improper algorithm identifier are accepted -for compatibility with SSLeay 0.4.5 :-) - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>, -L<rsa(3)|rsa(3)>, L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, -L<RSA_public_decrypt(3)|RSA_public_decrypt(3)> - -=head1 HISTORY - -RSA_sign() and RSA_verify() are available in all versions of SSLeay -and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod deleted file mode 100644 index e70380b..0000000 --- a/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod +++ /dev/null @@ -1,59 +0,0 @@ -=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)|ERR_get_error(3)>. - -=head1 BUGS - -These functions serve no recognizable purpose. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>, -L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, -L<RSA_verify(3)|RSA_verify(3)> - -=head1 HISTORY - -RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were -added in SSLeay 0.8. - -=cut diff --git a/openssl/doc/crypto/RSA_size.pod b/openssl/doc/crypto/RSA_size.pod deleted file mode 100644 index 5b7f835..0000000 --- a/openssl/doc/crypto/RSA_size.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -RSA_size - get RSA modulus size - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_size(const RSA *rsa); - -=head1 DESCRIPTION - -This function returns the RSA modulus size in bytes. It can be used to -determine how much memory must be allocated for an RSA encrypted -value. - -B<rsa-E<gt>n> must not be B<NULL>. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L<rsa(3)|rsa(3)> - -=head1 HISTORY - -RSA_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/SMIME_read_CMS.pod b/openssl/doc/crypto/SMIME_read_CMS.pod deleted file mode 100644 index acc5524..0000000 --- a/openssl/doc/crypto/SMIME_read_CMS.pod +++ /dev/null @@ -1,70 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_type(3)|CMS_type(3)> -L<SMIME_read_CMS(3)|SMIME_read_CMS(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> -L<CMS_decrypt(3)|CMS_decrypt(3)> - -=head1 HISTORY - -SMIME_read_CMS() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/SMIME_read_PKCS7.pod b/openssl/doc/crypto/SMIME_read_PKCS7.pod deleted file mode 100644 index 9d46715..0000000 --- a/openssl/doc/crypto/SMIME_read_PKCS7.pod +++ /dev/null @@ -1,73 +0,0 @@ -=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(). - -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)|ERR_get_error(3)>, L<PKCS7_type(3)|PKCS7_type(3)> -L<SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -SMIME_read_PKCS7() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/doc/crypto/SMIME_write_CMS.pod b/openssl/doc/crypto/SMIME_write_CMS.pod deleted file mode 100644 index 04bedfb..0000000 --- a/openssl/doc/crypto/SMIME_write_CMS.pod +++ /dev/null @@ -1,64 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> -L<CMS_decrypt(3)|CMS_decrypt(3)> - -=head1 HISTORY - -SMIME_write_CMS() was added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/SMIME_write_PKCS7.pod b/openssl/doc/crypto/SMIME_write_PKCS7.pod deleted file mode 100644 index ca6bd02..0000000 --- a/openssl/doc/crypto/SMIME_write_PKCS7.pod +++ /dev/null @@ -1,65 +0,0 @@ -=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 B<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 constructuted 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)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -SMIME_write_PKCS7() was added to OpenSSL 0.9.5 - -=cut diff --git a/openssl/doc/crypto/SSLeay_version.pod b/openssl/doc/crypto/SSLeay_version.pod deleted file mode 100644 index 1500c2a..0000000 --- a/openssl/doc/crypto/SSLeay_version.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -SSLeay_version - retrieve version/build information about OpenSSL library - -=head1 SYNOPSIS - - #include <openssl/crypto.h> - - const char *SSLeay_version(int type); - -=head1 DESCRIPTION - -SSLeay_version() returns a pointer to a constant string describing the -version of the OpenSSL library or giving information about the library -build. - -The following B<type> values are supported: - -=over 4 - -=item SSLEAY_VERSION - -The version of the OpenSSL library including the release date. - -=item SSLEAY_CFLAGS - -The compiler flags set for the compilation process in the form -"compiler: ..." if available or "compiler: information not available" -otherwise. - -=item SSLEAY_BUILT_ON - -The date of the build process in the form "built on: ..." if available -or "built on: date not available" otherwise. - -=item SSLEAY_PLATFORM - -The "Configure" target of the library build in the form "platform: ..." -if available or "platform: information not available" otherwise. - -=item SSLEAY_DIR - -The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "..."" -if available or "OPENSSLDIR: N/A" otherwise. - -=back - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item "not available" - -An invalid value for B<type> was given. - -=item Pointer to constant string - -Textual description. - -=back - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)> - -=head1 HISTORY - -B<SSLEAY_DIR> was added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod b/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod deleted file mode 100644 index 4716e7e..0000000 --- a/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod +++ /dev/null @@ -1,74 +0,0 @@ -=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(X509_NAME_ENTRY *ne); - ASN1_STRING * X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne); - - int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, 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,unsigned char *bytes, int len); - X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, 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 RETURN VALUES - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, -L<OBJ_nid2obj(3)|OBJ_nid2obj(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod b/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod deleted file mode 100644 index 3bdc07f..0000000 --- a/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod +++ /dev/null @@ -1,116 +0,0 @@ -=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, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set); - - int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set); - - int X509_NAME_add_entry(X509_NAME *name,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)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> - -=head1 HISTORY - -=cut diff --git a/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod b/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod deleted file mode 100644 index cdec4b1..0000000 --- a/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod +++ /dev/null @@ -1,118 +0,0 @@ -=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,ASN1_OBJECT *obj, int lastpos); - - int X509_NAME_entry_count(X509_NAME *name); - X509_NAME_ENTRY *X509_NAME_get_entry(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, 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 muticharacter 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)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/X509_NAME_print_ex.pod b/openssl/doc/crypto/X509_NAME_print_ex.pod deleted file mode 100644 index d73520f..0000000 --- a/openssl/doc/crypto/X509_NAME_print_ex.pod +++ /dev/null @@ -1,107 +0,0 @@ -=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, X509_NAME *nm, int indent, unsigned long flags); - int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags); - char * X509_NAME_oneline(X509_NAME *a,char *buf,int size); - int X509_NAME_print(BIO *bp, 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)|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)|ASN1_STRING_print_ex(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/X509_STORE_CTX_get_error.pod b/openssl/doc/crypto/X509_STORE_CTX_get_error.pod deleted file mode 100644 index be00ff1..0000000 --- a/openssl/doc/crypto/X509_STORE_CTX_get_error.pod +++ /dev/null @@ -1,305 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, X509_STORE_CTX_get_error_depth, X509_STORE_CTX_get_current_cert, X509_STORE_CTX_get1_chain, X509_verify_cert_error_string - get or set certificate verification status information - -=head1 SYNOPSIS - - #include <openssl/x509.h> - #include <openssl/x509_vfy.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); - X509 * X509_STORE_CTX_get_current_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_get_current_cert() returns the certificate in B<ctx> which -caused the error or B<NULL> if no certificate is relevant. - -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 cerificate 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 pathlength 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)|X509_verify_cert(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod b/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod deleted file mode 100644 index 8a9243d..0000000 --- a/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data - add application specific data to X509_STORE_CTX structures - -=head1 SYNOPSIS - - #include <openssl/x509_vfy.h> - - int X509_STORE_CTX_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); - - void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in X509_STORE_CTX structures. -Their usage is identical to that of RSA_get_ex_new_index(), RSA_set_ex_data() -and RSA_get_ex_data() as described in L<RSA_get_ex_new_index(3)>. - -=head1 NOTES - -This mechanism is used internally by the B<ssl> library to store the B<SSL> -structure associated with a verification operation in an B<X509_STORE_CTX> -structure. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)> - -=head1 HISTORY - -X509_STORE_CTX_get_ex_new_index(), X509_STORE_CTX_set_ex_data() and -X509_STORE_CTX_get_ex_data() are available since OpenSSL 0.9.5. - -=cut diff --git a/openssl/doc/crypto/X509_STORE_CTX_new.pod b/openssl/doc/crypto/X509_STORE_CTX_new.pod deleted file mode 100644 index eb38b0a..0000000 --- a/openssl/doc/crypto/X509_STORE_CTX_new.pod +++ /dev/null @@ -1,127 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_set_chain, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default - 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_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); - - void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx,X509 *x); - void X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,STACK_OF(X509) *sk); - 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); - -=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. - -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_XTORE_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_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 vertified in B<ctx> to -B<x>. - -X509_STORE_CTX_set_chain() sets the additional certificate chain used by B<ctx> -to B<sk>. - -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_VERIFY_PARAM *X509_STORE_CTX_get0_param() retrieves an intenal pointer -to the verification parameters associated with B<ctx>. - -X509_STORE_CTX_set0_param() sets the intenal 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>. - -=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. Legacy -applications might implicitly use an B<X509_STORE_CTX> like this: - - X509_STORE_CTX ctx; - X509_STORE_CTX_init(&ctx, store, cert, chain); - -this is B<not> recommended in new applications they should instead do: - - X509_STORE_CTX *ctx; - ctx = X509_STORE_CTX_new(); - if (ctx == NULL) - /* Bad error */ - X509_STORE_CTX_init(ctx, store, cert, chain); - -=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_trusted_stack(), -X509_STORE_CTX_set_cert(), X509_STORE_CTX_set_chain(), -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. - -=head1 SEE ALSO - -L<X509_verify_cert(3)|X509_verify_cert(3)> -L<X509_VERIFY_PARAM_set_flags(3)|X509_VERIFY_PARAM_set_flags(3)> - -=head1 HISTORY - -X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0 - -=cut diff --git a/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod b/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod deleted file mode 100644 index b9787a6..0000000 --- a/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod +++ /dev/null @@ -1,161 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_set_verify_cb - set verification callback - -=head1 SYNOPSIS - - #include <openssl/x509_vfy.h> - - void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, - int (*verify_cb)(int ok, 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 and 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. - -=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)|X509_STORE_CTX_get_error(3)> -L<X509_STORE_set_verify_cb_func(3)|X509_STORE_set_verify_cb_func(3)> -L<X509_STORE_CTX_get_ex_new_index(3)|X509_STORE_CTX_get_ex_new_index(3)> - -=head1 HISTORY - -X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and -OpenSSL. - -=cut diff --git a/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod b/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod deleted file mode 100644 index 29e3bbe..0000000 --- a/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb - set verification callback - -=head1 SYNOPSIS - - #include <openssl/x509_vfy.h> - - void X509_STORE_set_verify_cb(X509_STORE *st, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); - - void X509_STORE_set_verify_cb_func(X509_STORE *st, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); - -=head1 DESCRIPTION - -X509_STORE_set_verify_cb() sets the verification callback of B<ctx> to -B<verify_cb> overwriting any existing callback. - -X509_STORE_set_verify_cb_func() also sets the verification callback but it -is implemented as a macro. - -=head1 NOTES - -The verification callback from an B<X509_STORE> is inherited by -the corresponding B<X509_STORE_CTX> structure when it is initialized. This can -be used to set the verification callback when the B<X509_STORE_CTX> is -otherwise inaccessible (for example during S/MIME verification). - -=head1 BUGS - -The macro version of this function was the only one available before -OpenSSL 1.0.0. - -=head1 RETURN VALUES - -X509_STORE_set_verify_cb() and X509_STORE_set_verify_cb_func() do not return -a value. - -=head1 SEE ALSO - -L<X509_STORE_CTX_set_verify_cb(3)|X509_STORE_CTX_set_verify_cb(3)> -L<CMS_verify(3)|CMS_verify(3)> - -=head1 HISTORY - -X509_STORE_set_verify_cb_func() is available in all versions of SSLeay and -OpenSSL. - -X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0. - -=cut diff --git a/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod deleted file mode 100644 index 44792f9..0000000 --- a/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod +++ /dev/null @@ -1,244 +0,0 @@ -=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_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_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_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); - - 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); - - 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_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 untrusted CA certificates that can appear in a -chain. - -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 -B<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 -identifer 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_purpose(), X509_VERIFY_PARAM_set_trust(), -X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(), -X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_set_hostflags(), -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_set_time() and X509_VERIFY_PARAM_set_depth() do not return -values. - -X509_VERIFY_PARAM_get_depth() returns the current verification depth. - -=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 peformed. 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> ise 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 -cerificate 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. - -The B<X509_V_FLAG_CB_ISSUER_CHECK> flag enables debugging of certificate -issuer checks. It is B<not> needed unless you are logging certificate -verification. If this flag is set then additional status codes will be sent -to the verification callback and it B<must> be prepared to handle such cases -without assuming they are hard errors. - -The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative -chains. By default, when building a certificate chain, if the first certificate -chain found is not trusted, then OpenSSL will continue to check to see if an -alternative chain can be found that is trusted. With this flag set the behaviour -will match that of OpenSSL versions prior to 1.0.2b. - -=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)|X509_verify_cert(3)>, -L<X509_check_host(3)|X509_check_host(3)>, -L<X509_check_email(3)|X509_check_email(3)>, -L<X509_check_ip(3)|X509_check_ip(3)> - -=head1 HISTORY - -The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.0.2b - -=cut diff --git a/openssl/doc/crypto/X509_check_host.pod b/openssl/doc/crypto/X509_check_host.pod deleted file mode 100644 index 521b9f5..0000000 --- a/openssl/doc/crypto/X509_check_host.pod +++ /dev/null @@ -1,140 +0,0 @@ -=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_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. - -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 aplies 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)|SSL_get_verify_result(3)>, -L<X509_VERIFY_PARAM_set1_host(3)|X509_VERIFY_PARAM_set1_host(3)>, -L<X509_VERIFY_PARAM_add1_host(3)|X509_VERIFY_PARAM_add1_host(3)>, -L<X509_VERIFY_PARAM_set1_email(3)|X509_VERIFY_PARAM_set1_email(3)>, -L<X509_VERIFY_PARAM_set1_ip(3)|X509_VERIFY_PARAM_set1_ip(3)>, -L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)> - -=head1 HISTORY - -These functions were added in OpenSSL 1.0.2. - -=cut diff --git a/openssl/doc/crypto/X509_new.pod b/openssl/doc/crypto/X509_new.pod deleted file mode 100644 index d388723..0000000 --- a/openssl/doc/crypto/X509_new.pod +++ /dev/null @@ -1,39 +0,0 @@ -=pod - -=head1 NAME - -X509_new, X509_free - X509 certificate ASN1 allocation functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509 *X509_new(void); - void X509_free(X509 *a); - -=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. - -X509_free() frees up the B<X509> structure B<a>. - -=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)|ERR_get_error(3)>. -Otherwise it returns a pointer to the newly allocated structure. - -X509_free() returns no value. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -X509_new() and X509_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/X509_verify_cert.pod b/openssl/doc/crypto/X509_verify_cert.pod deleted file mode 100644 index 4689e3a..0000000 --- a/openssl/doc/crypto/X509_verify_cert.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -X509_verify_cert - discover and verify X509 certificte 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)|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 -functiosn which use B<x509_vfy.h>. - -=head1 SEE ALSO - -L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> - -=head1 HISTORY - -X509_verify_cert() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/bio.pod b/openssl/doc/crypto/bio.pod deleted file mode 100644 index f923922..0000000 --- a/openssl/doc/crypto/bio.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -bio - I/O abstraction - -=head1 SYNOPSIS - - #include <openssl/bio.h> - -TBA - - -=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). - -=head1 SEE ALSO - -L<BIO_ctrl(3)|BIO_ctrl(3)>, -L<BIO_f_base64(3)|BIO_f_base64(3)>, L<BIO_f_buffer(3)|BIO_f_buffer(3)>, -L<BIO_f_cipher(3)|BIO_f_cipher(3)>, L<BIO_f_md(3)|BIO_f_md(3)>, -L<BIO_f_null(3)|BIO_f_null(3)>, L<BIO_f_ssl(3)|BIO_f_ssl(3)>, -L<BIO_find_type(3)|BIO_find_type(3)>, L<BIO_new(3)|BIO_new(3)>, -L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>, -L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>, -L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>, -L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>, -L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>, -L<BIO_set_callback(3)|BIO_set_callback(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)> diff --git a/openssl/doc/crypto/blowfish.pod b/openssl/doc/crypto/blowfish.pod deleted file mode 100644 index 5b2d274..0000000 --- a/openssl/doc/crypto/blowfish.pod +++ /dev/null @@ -1,112 +0,0 @@ -=pod - -=head1 NAME - -blowfish, 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)|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)|EVP_EncryptInit(3)> etc. instead of calling the -blowfish functions directly. - -=head1 SEE ALSO - -L<des_modes(7)|des_modes(7)> - -=head1 HISTORY - -The Blowfish functions are available in all versions of SSLeay and OpenSSL. - -=cut - diff --git a/openssl/doc/crypto/bn.pod b/openssl/doc/crypto/bn.pod deleted file mode 100644 index cd2f8e5..0000000 --- a/openssl/doc/crypto/bn.pod +++ /dev/null @@ -1,181 +0,0 @@ -=pod - -=head1 NAME - -bn - multiprecision integer arithmetics - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_new(void); - void BN_free(BIGNUM *a); - void BN_init(BIGNUM *); - void BN_clear(BIGNUM *a); - void BN_clear_free(BIGNUM *a); - - BN_CTX *BN_CTX_new(void); - void BN_CTX_init(BN_CTX *c); - void BN_CTX_free(BN_CTX *c); - - BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); - BIGNUM *BN_dup(const BIGNUM *a); - - BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b); - - int BN_num_bytes(const BIGNUM *a); - int BN_num_bits(const BIGNUM *a); - int BN_num_bits_word(BN_ULONG w); - - void BN_set_negative(BIGNUM *a, int n); - int BN_is_negative(const BIGNUM *a); - - 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 *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sqr(BIGNUM *ret, 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); - - 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); - - 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); - - int BN_zero(BIGNUM *a); - int BN_one(BIGNUM *a); - const BIGNUM *BN_value_one(void); - int BN_set_word(BIGNUM *a, unsigned long w); - unsigned long BN_get_word(BIGNUM *a); - - 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); - - BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, - BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); - int BN_is_prime(const BIGNUM *p, int nchecks, - void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); - - 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); - - int BN_bn2bin(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_bin2bn(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); - - BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, - BN_CTX *ctx); - - BN_RECP_CTX *BN_RECP_CTX_new(void); - void BN_RECP_CTX_init(BN_RECP_CTX *recp); - 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_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_RECP_CTX *recp, BN_CTX *ctx); - - BN_MONT_CTX *BN_MONT_CTX_new(void); - void BN_MONT_CTX_init(BN_MONT_CTX *ctx); - 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); - - 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); - unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); - void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); - 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 - -This library performs arithmetic operations on integers of arbitrary -size. It was written for use in public key cryptography, such as RSA -and Diffie-Hellman. - -It uses dynamic memory allocation for storing its data structures. -That means that there is no limit on the size of the numbers -manipulated by these functions, but return values must always be -checked in case a memory allocation error has occurred. - -The basic object in this library is a B<BIGNUM>. It is used to hold a -single large integer. This type should be considered opaque and fields -should not be modified or accessed directly. - -The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>; -L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations. -Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)> -describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of -random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime -numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion -of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. - -=head1 SEE ALSO - -L<bn_internal(3)|bn_internal(3)>, -L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, -L<BN_copy(3)|BN_copy(3)>, L<BN_swap(3)|BN_swap(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, -L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>, -L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>, -L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>, -L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>, -L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>, -L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>, -L<BN_BLINDING_new(3)|BN_BLINDING_new(3)> - -=cut diff --git a/openssl/doc/crypto/bn_internal.pod b/openssl/doc/crypto/bn_internal.pod deleted file mode 100644 index 91840b0..0000000 --- a/openssl/doc/crypto/bn_internal.pod +++ /dev/null @@ -1,238 +0,0 @@ -=pod - -=head1 NAME - -bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, -bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, -bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, -bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, -bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive, -bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, -bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low - BIGNUM -library internal functions - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); - BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, - BN_ULONG w); - void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); - BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); - BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - - void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); - void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); - - int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); - - void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, - int nb); - void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); - void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, - int dna,int dnb,BN_ULONG *tmp); - void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n, int tna,int tnb, BN_ULONG *tmp); - void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n2, BN_ULONG *tmp); - void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l, - int n2, BN_ULONG *tmp); - - void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); - void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); - - void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); - - BIGNUM *bn_expand(BIGNUM *a, int bits); - BIGNUM *bn_wexpand(BIGNUM *a, int n); - BIGNUM *bn_expand2(BIGNUM *a, int n); - void bn_fix_top(BIGNUM *a); - - void bn_check_top(BIGNUM *a); - void bn_print(BIGNUM *a); - void bn_dump(BN_ULONG *d, int n); - void bn_set_max(BIGNUM *a); - void bn_set_high(BIGNUM *r, BIGNUM *a, int n); - void bn_set_low(BIGNUM *r, BIGNUM *a, int n); - -=head1 DESCRIPTION - -This page documents the internal functions used by the OpenSSL -B<BIGNUM> implementation. They are described here to facilitate -debugging and extending the library. They are I<not> to be used by -applications. - -=head2 The BIGNUM structure - - typedef struct bignum_st BIGNUM; - - struct bignum_st - { - BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */ - int top; /* Index of last used d +1. */ - /* The next are internal book keeping for bn_expand. */ - int dmax; /* Size of the d array. */ - int neg; /* one if the number is negative */ - int flags; - }; - - -The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>), -least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits -in size, depending on the 'number of bits' (B<BITS2>) specified in -C<openssl/bn.h>. - -B<dmax> is the size of the B<d> array that has been allocated. B<top> -is the number of words being used, so for a value of 4, bn.d[0]=4 and -bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is -B<0>, the B<d> field can be B<NULL> and B<top> == B<0>. - -B<flags> is a bit field of flags which are defined in C<openssl/bn.h>. The -flags begin with B<BN_FLG_>. The macros BN_set_flags(b,n) and -BN_get_flags(b,n) exist to enable or fetch flag(s) B<n> from B<BIGNUM> -structure B<b>. - -Various routines in this library require the use of temporary -B<BIGNUM> variables during their execution. 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. This structure contains B<BN_CTX_NUM> B<BIGNUM>s, see -L<BN_CTX_start(3)|BN_CTX_start(3)>. - -=head2 Low-level arithmetic operations - -These functions are implemented in C and for several platforms in -assembly language: - -bn_mul_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> word -arrays B<rp> and B<ap>. It computes B<ap> * B<w>, places the result -in B<rp>, and returns the high word (carry). - -bn_mul_add_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> -word arrays B<rp> and B<ap>. It computes B<ap> * B<w> + B<rp>, places -the result in B<rp>, and returns the high word (carry). - -bn_sqr_words(B<rp>, B<ap>, B<n>) operates on the B<num> word array -B<ap> and the 2*B<num> word array B<ap>. It computes B<ap> * B<ap> -word-wise, and places the low and high bytes of the result in B<rp>. - -bn_div_words(B<h>, B<l>, B<d>) divides the two word number (B<h>,B<l>) -by B<d> and returns the result. - -bn_add_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word -arrays B<ap>, B<bp> and B<rp>. It computes B<ap> + B<bp>, places the -result in B<rp>, and returns the high word (carry). - -bn_sub_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word -arrays B<ap>, B<bp> and B<rp>. It computes B<ap> - B<bp>, places the -result in B<rp>, and returns the carry (1 if B<bp> E<gt> B<ap>, 0 -otherwise). - -bn_mul_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and -B<b> and the 8 word array B<r>. It computes B<a>*B<b> and places the -result in B<r>. - -bn_mul_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and -B<b> and the 16 word array B<r>. It computes B<a>*B<b> and places the -result in B<r>. - -bn_sqr_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and -B<b> and the 8 word array B<r>. - -bn_sqr_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and -B<b> and the 16 word array B<r>. - -The following functions are implemented in C: - -bn_cmp_words(B<a>, B<b>, B<n>) operates on the B<n> word arrays B<a> -and B<b>. It returns 1, 0 and -1 if B<a> is greater than, equal and -less than B<b>. - -bn_mul_normal(B<r>, B<a>, B<na>, B<b>, B<nb>) operates on the B<na> -word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word -array B<r>. It computes B<a>*B<b> and places the result in B<r>. - -bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word -arrays B<r>, B<a> and B<b>. It computes the B<n> low words of -B<a>*B<b> and places the result in B<r>. - -bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<dna>, B<dnb>, B<t>) operates -on the word arrays B<a> and B<b> of length B<n2>+B<dna> and B<n2>+B<dnb> -(B<dna> and B<dnb> are currently allowed to be 0 or negative) and the 2*B<n2> -word arrays B<r> and B<t>. B<n2> must be a power of 2. It computes -B<a>*B<b> and places the result in B<r>. - -bn_mul_part_recursive(B<r>, B<a>, B<b>, B<n>, B<tna>, B<tnb>, B<tmp>) -operates on the word arrays B<a> and B<b> of length B<n>+B<tna> and -B<n>+B<tnb> and the 4*B<n> word arrays B<r> and B<tmp>. - -bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the -B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a> -and B<b>. - -bn_mul_high(B<r>, B<a>, B<b>, B<l>, B<n2>, B<tmp>) operates on the -B<n2> word arrays B<r>, B<a>, B<b> and B<l> (?) and the 3*B<n2> word -array B<tmp>. - -BN_mul() calls bn_mul_normal(), or an optimized implementation if the -factors have the same size: bn_mul_comba8() is used if they are 8 -words long, bn_mul_recursive() if they are larger than -B<BN_MULL_SIZE_NORMAL> and the size is an exact multiple of the word -size, and bn_mul_part_recursive() for others that are larger than -B<BN_MULL_SIZE_NORMAL>. - -bn_sqr_normal(B<r>, B<a>, B<n>, B<tmp>) operates on the B<n> word array -B<a> and the 2*B<n> word arrays B<tmp> and B<r>. - -The implementations use the following macros which, depending on the -architecture, may use "long long" C operations or inline assembler. -They are defined in C<bn_lcl.h>. - -mul(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<c> and places the -low word of the result in B<r> and the high word in B<c>. - -mul_add(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<r>+B<c> and -places the low word of the result in B<r> and the high word in B<c>. - -sqr(B<r0>, B<r1>, B<a>) computes B<a>*B<a> and places the low word -of the result in B<r0> and the high word in B<r1>. - -=head2 Size changes - -bn_expand() ensures that B<b> has enough space for a B<bits> bit -number. bn_wexpand() ensures that B<b> has enough space for an -B<n> word number. If the number has to be expanded, both macros -call bn_expand2(), which allocates a new B<d> array and copies the -data. They return B<NULL> on error, B<b> otherwise. - -The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most -significant non-zero word plus one when B<a> has shrunk. - -=head2 Debugging - -bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top -E<lt>= (a)-E<gt>dmax)>. A violation will cause the program to abort. - -bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d> -(in reverse order, i.e. most significant word first) to stderr. - -bn_set_max() makes B<a> a static number with a B<dmax> of its current size. -This is used by bn_set_low() and bn_set_high() to make B<r> a read-only -B<BIGNUM> that contains the B<n> low or high words of B<a>. - -If B<BN_DEBUG> is not defined, bn_check_top(), bn_print(), bn_dump() -and bn_set_max() are defined as empty macros. - -=head1 SEE ALSO - -L<bn(3)|bn(3)> - -=cut diff --git a/openssl/doc/crypto/buffer.pod b/openssl/doc/crypto/buffer.pod deleted file mode 100644 index 52c5c84..0000000 --- a/openssl/doc/crypto/buffer.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow - simple -character array structure - -BUF_strdup, BUF_strndup, BUF_memdup, BUF_strlcpy, BUF_strlcat - -standard C library equivalents - -=head1 SYNOPSIS - - #include <openssl/buffer.h> - - BUF_MEM *BUF_MEM_new(void); - - void BUF_MEM_free(BUF_MEM *a); - - int BUF_MEM_grow(BUF_MEM *str, int len); - - char *BUF_strdup(const char *str); - - char *BUF_strndup(const char *str, size_t siz); - - void *BUF_memdup(const void *data, size_t siz); - - size_t BUF_strlcpy(char *dst, const char *src, size_t size); - - size_t BUF_strlcat(char *dst, const char *src, size_t size); - - size_t BUF_strnlen(const char *str, size_t maxlen); - -=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_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_strdup(), BUF_strndup(), BUF_memdup(), BUF_strlcpy(), -BUF_strlcat() and BUF_strnlen are equivalents of the standard C -library functions. The dup() functions use OPENSSL_malloc() underneath -and so should be used in preference to the standard library for memory -leak checking or replacing the malloc() function. - -Memory allocated from these functions should be freed up using the -OPENSSL_free() function. - -BUF_strndup makes the explicit guarantee that it will never read past -the first B<siz> bytes of B<str>. - -=head1 RETURN VALUES - -BUF_MEM_new() returns the buffer or NULL on error. - -BUF_MEM_free() has no return value. - -BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>). - -=head1 SEE ALSO - -L<bio(3)|bio(3)> - -=head1 HISTORY - -BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all -versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8. - -=cut diff --git a/openssl/doc/crypto/crypto.pod b/openssl/doc/crypto/crypto.pod deleted file mode 100644 index f18edfe..0000000 --- a/openssl/doc/crypto/crypto.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -crypto - OpenSSL cryptographic library - -=head1 SYNOPSIS - -=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. - -=head1 OVERVIEW - -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 and a cryptographic pseudo-random number generator. - -=over 4 - -=item SYMMETRIC CIPHERS - -L<blowfish(3)|blowfish(3)>, L<cast(3)|cast(3)>, L<des(3)|des(3)>, -L<idea(3)|idea(3)>, L<rc2(3)|rc2(3)>, L<rc4(3)|rc4(3)>, L<rc5(3)|rc5(3)> - -=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT - -L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rsa(3)|rsa(3)> - -=item CERTIFICATES - -L<x509(3)|x509(3)>, L<x509v3(3)|x509v3(3)> - -=item AUTHENTICATION CODES, HASH FUNCTIONS - -L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, L<md4(3)|md4(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)> - -=item AUXILIARY FUNCTIONS - -L<err(3)|err(3)>, L<threads(3)|threads(3)>, L<rand(3)|rand(3)>, -L<OPENSSL_VERSION_NUMBER(3)|OPENSSL_VERSION_NUMBER(3)> - -=item INPUT/OUTPUT, DATA ENCODING - -L<asn1(3)|asn1(3)>, L<bio(3)|bio(3)>, L<evp(3)|evp(3)>, L<pem(3)|pem(3)>, -L<pkcs7(3)|pkcs7(3)>, L<pkcs12(3)|pkcs12(3)> - -=item INTERNAL FUNCTIONS - -L<bn(3)|bn(3)>, L<buffer(3)|buffer(3)>, L<ec(3)|ec(3)>, L<lhash(3)|lhash(3)>, -L<objects(3)|objects(3)>, L<stack(3)|stack(3)>, -L<txt_db(3)|txt_db(3)> - -=back - -=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, 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 SEE ALSO - -L<openssl(1)|openssl(1)>, L<ssl(3)|ssl(3)> - -=cut diff --git a/openssl/doc/crypto/d2i_ASN1_OBJECT.pod b/openssl/doc/crypto/d2i_ASN1_OBJECT.pod deleted file mode 100644 index 45bb184..0000000 --- a/openssl/doc/crypto/d2i_ASN1_OBJECT.pod +++ /dev/null @@ -1,29 +0,0 @@ -=pod - -=head1 NAME - -d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions - -=head1 SYNOPSIS - - #include <openssl/objects.h> - - ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length); - int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an ASN1 OBJECT IDENTIFIER. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/d2i_CMS_ContentInfo.pod b/openssl/doc/crypto/d2i_CMS_ContentInfo.pod deleted file mode 100644 index 6ddb2f6..0000000 --- a/openssl/doc/crypto/d2i_CMS_ContentInfo.pod +++ /dev/null @@ -1,29 +0,0 @@ -=pod - -=head1 NAME - -d2i_CMS_ContentInfo, i2d_CMS_ContentInfo - CMS ContentInfo functions - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_ContentInfo *d2i_CMS_ContentInfo(CMS_ContentInfo **a, unsigned char **pp, long length); - int i2d_CMS_ContentInfo(CMS_ContentInfo *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an CMS ContentInfo structure. - -Otherwise they behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 0.9.8 - -=cut diff --git a/openssl/doc/crypto/d2i_DHparams.pod b/openssl/doc/crypto/d2i_DHparams.pod deleted file mode 100644 index 1e98aeb..0000000 --- a/openssl/doc/crypto/d2i_DHparams.pod +++ /dev/null @@ -1,30 +0,0 @@ -=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. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/d2i_DSAPublicKey.pod b/openssl/doc/crypto/d2i_DSAPublicKey.pod deleted file mode 100644 index e999376..0000000 --- a/openssl/doc/crypto/d2i_DSAPublicKey.pod +++ /dev/null @@ -1,83 +0,0 @@ -=pod - -=head1 NAME - -d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey, -d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding -and parsing functions. - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - #include <openssl/x509.h> - - DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); - - DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length); - - int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp); - - DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - - DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAparams(const DSA *a, unsigned char **pp); - - DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length); - - int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); - -=head1 DESCRIPTION - -d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key -components structure. - -d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode an DSA public key using -a SubjectPublicKeyInfo (certificate public key) structure. - -d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key -components. - -d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using -a B<Dss-Parms> structure as defined in RFC2459. - -d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a -B<Dss-Sig-Value> structure as defined in RFC2459. - -The usage of all of these functions is similar to the d2i_X509() and -i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 NOTES - -The B<DSA> structure passed to the private key encoding functions should have -all the private key components present. - -The data encoded by the private key functions is unencrypted and therefore -offers no private key security. - -The B<DSA_PUBKEY> functions should be used in preference to the B<DSAPublicKey> -functions when encoding public keys because they use a standard format. - -The B<DSAPublicKey> functions use an non standard format the actual data encoded -depends on the value of the B<write_params> field of the B<a> key parameter. -If B<write_params> is zero then only the B<pub_key> field is encoded as an -B<INTEGER>. If B<write_params> is 1 then a B<SEQUENCE> consisting of the -B<p>, B<q>, B<g> and B<pub_key> respectively fields are encoded. - -The B<DSAPrivateKey> functions also use a non standard structure consiting -consisting of a SEQUENCE containing the B<p>, B<q>, B<g> and B<pub_key> and -B<priv_key> fields respectively. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/d2i_ECPKParameters.pod b/openssl/doc/crypto/d2i_ECPKParameters.pod deleted file mode 100644 index 704b4ab..0000000 --- a/openssl/doc/crypto/d2i_ECPKParameters.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp, ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities - -=head1 SYNOPSIS - - #include <openssl/ec.h> - - EC_GROUP *d2i_ECPKParameters(EC_GROUP **px, const unsigned char **in, long len); - int i2d_ECPKParameters(const EC_GROUP *x, unsigned char **out); - #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) - #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) - #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ - (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) - #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ - (unsigned char *)(x)) - 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 encode and decode routines encode and parse the public parameters for an -B<EC_GROUP> structure, which represents a curve. - -d2i_ECPKParameters() attempts to decode B<len> bytes at B<*in>. If -successful a pointer to the B<EC_GROUP> structure is returned. If an error -occurred then B<NULL> is returned. If B<px> is not B<NULL> then the -returned structure is written to B<*px>. If B<*px> is not B<NULL> -then it is assumed that B<*px> contains a valid B<EC_GROUP> -structure and an attempt is made to reuse it. If the call is -successful B<*in> is incremented to the byte following the -parsed data. - -i2d_ECPKParameters() encodes the structure pointed to by B<x> into DER format. -If B<out> is not B<NULL> is writes the DER encoded data to the buffer -at B<*out>, 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<*out> is B<NULL> memory will be allocated for a buffer and the encoded -data written to it. In this case B<*out> is not incremented and it points to -the start of the data just written. - -d2i_ECPKParameters_bio() is similar to d2i_ECPKParameters() except it attempts -to parse data from BIO B<bp>. - -d2i_ECPKParameters_fp() is similar to d2i_ECPKParameters() except it attempts -to parse data from FILE pointer B<fp>. - -i2d_ECPKParameters_bio() is similar to i2d_ECPKParameters() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -i2d_ECPKParameters_fp() is similar to i2d_ECPKParameters() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -These functions are very similar to the X509 functions described in L<d2i_X509(3)|d2i_X509(3)>, -where further notes and examples are available. - -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 - -d2i_ECPKParameters(), d2i_ECPKParameters_bio() and d2i_ECPKParameters_fp() return a valid B<EC_GROUP> structure -or B<NULL> if an error occurs. - -i2d_ECPKParameters() returns the number of bytes successfully encoded or a negative -value if an error occurs. - -i2d_ECPKParameters_bio(), i2d_ECPKParameters_fp(), ECPKParameters_print and ECPKParameters_print_fp -return 1 for success and 0 if an error occurs. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_X509(3)|d2i_X509(3)> - -=cut diff --git a/openssl/doc/crypto/d2i_ECPrivateKey.pod b/openssl/doc/crypto/d2i_ECPrivateKey.pod deleted file mode 100644 index adeffe6..0000000 --- a/openssl/doc/crypto/d2i_ECPrivateKey.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -i2d_ECPrivateKey, d2i_ECPrivate_key - Encode and decode functions for saving and -reading EC_KEY structures - -=head1 SYNOPSIS - - #include <openssl/ec.h> - - EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); - - 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 ECPrivateKey encode and decode routines encode and parse an -B<EC_KEY> structure into a binary format (ASN.1 DER) and back again. - -These functions are similar to the d2i_X509() functions, and you should refer to -that page for a detailed description (see L<d2i_X509(3)|d2i_X509(3)>). - -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)|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 - -d2i_ECPrivateKey() returns a valid B<EC_KEY> structure or B<NULL> if an error -occurs. The error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. - -i2d_ECPrivateKey() returns the number of bytes successfully encoded or a -negative value if an error occurs. The error code can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. - -EC_KEY_get_enc_flags returns the value of the current encoding flags for the -EC_KEY. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, -L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>, -L<EC_POINT_add(3)|EC_POINT_add(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, -L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>, -L<d2i_ECPrivateKey(3)|d2i_ECPrivateKey(3)> - -=cut diff --git a/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod b/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod deleted file mode 100644 index a54b779..0000000 --- a/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod +++ /dev/null @@ -1,56 +0,0 @@ -=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 the L<pem(3)|pem(3)> manual page. - -=head1 NOTES - -Before using these functions L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)> -should be called to initialize the internal algorithm lookup tables otherwise errors about -unknown algorithms will occur if an attempt is made to decrypt a private key. - -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)|BIO_s_mem(3)> for details. - -=head1 SEE ALSO - -L<pem(3)|pem(3)> - -=cut diff --git a/openssl/doc/crypto/d2i_PrivateKey.pod b/openssl/doc/crypto/d2i_PrivateKey.pod deleted file mode 100644 index e06ab6c..0000000 --- a/openssl/doc/crypto/d2i_PrivateKey.pod +++ /dev/null @@ -1,59 +0,0 @@ -=pod - -=head1 NAME - -d2i_Private_key, d2i_AutoPrivateKey, i2d_PrivateKey - 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_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp, - long length); - int i2d_PrivateKey(EVP_PKEY *a, unsigned char **pp); - -=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_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. - -These functions are similar to the d2i_X509() functions, and you should refer to -that page for a detailed description (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(3)>, -L<d2i_PKCS8PrivateKey(3)> - -=cut diff --git a/openssl/doc/crypto/d2i_RSAPublicKey.pod b/openssl/doc/crypto/d2i_RSAPublicKey.pod deleted file mode 100644 index aa6078b..0000000 --- a/openssl/doc/crypto/d2i_RSAPublicKey.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, -d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA, -d2i_Netscape_RSA - RSA public and private key encoding functions. - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - #include <openssl/x509.h> - - RSA * d2i_RSAPublicKey(RSA **a, const unsigned char **pp, long length); - - int i2d_RSAPublicKey(RSA *a, unsigned char **pp); - - RSA * d2i_RSA_PUBKEY(RSA **a, const unsigned char **pp, long length); - - int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp); - - RSA * d2i_RSAPrivateKey(RSA **a, const unsigned char **pp, long length); - - int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); - - 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 - -d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 RSAPublicKey -structure. - -d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY() decode and encode an RSA public key using -a SubjectPublicKeyInfo (certificate public key) structure. - -d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1 RSAPrivateKey -structure. - -d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in -NET format. - -The usage of all of these functions is similar to the d2i_X509() and -i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 NOTES - -The B<RSA> structure passed to the private key encoding functions should have -all the PKCS#1 private key components present. - -The data encoded by the private key functions is unencrypted and therefore -offers no private key security. - -The NET format functions are present to provide compatibility with certain very -old software. This format has some severe security weaknesses and should be -avoided if possible. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/d2i_X509.pod b/openssl/doc/crypto/d2i_X509.pod deleted file mode 100644 index 2743bc7..0000000 --- a/openssl/doc/crypto/d2i_X509.pod +++ /dev/null @@ -1,272 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, -i2d_X509_fp - X509 encode and decode functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509 *d2i_X509(X509 **px, const unsigned char **in, long len); - X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); - int i2d_X509(X509 *x, unsigned char **out); - int i2d_X509_AUX(X509 *x, unsigned char **out); - - X509 *d2i_X509_bio(BIO *bp, X509 **x); - X509 *d2i_X509_fp(FILE *fp, X509 **x); - - int i2d_X509_bio(BIO *bp, X509 *x); - int i2d_X509_fp(FILE *fp, X509 *x); - - int i2d_re_X509_tbs(X509 *x, unsigned char **out); - -=head1 DESCRIPTION - -The X509 encode and decode routines encode and parse an -B<X509> structure, which represents an X509 certificate. - -d2i_X509() attempts to decode B<len> bytes at B<*in>. If -successful a pointer to the B<X509> structure is returned. If an error -occurred then B<NULL> is returned. If B<px> is not B<NULL> then the -returned structure is written to B<*px>. If B<*px> is not B<NULL> -then it is assumed that B<*px> contains a valid B<X509> -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). - -If the call is successful B<*in> is incremented to the byte following the -parsed data. - -d2i_X509_AUX() is similar to d2i_X509() 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() encodes the structure pointed to by B<x> into DER format. -If B<out> is not B<NULL> is writes the DER encoded data to the buffer -at B<*out>, 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. - -For OpenSSL 0.9.7 and later if B<*out> is B<NULL> memory will be -allocated for a buffer and the encoded data written to it. In this -case B<*out> is not incremented and it points to the start of the -data just written. - -i2d_X509_AUX() is similar to i2d_X509(), 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, this is a non-standard OpenSSL-specific data format. - -d2i_X509_bio() is similar to d2i_X509() except it attempts -to parse data from BIO B<bp>. - -d2i_X509_fp() is similar to d2i_X509() except it attempts -to parse data from FILE pointer B<fp>. - -i2d_X509_bio() is similar to i2d_X509() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -i2d_X509_fp() is similar to i2d_X509() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -i2d_re_X509_tbs() is similar to i2d_X509() except it encodes -only the TBSCertificate portion of the certificate. - -=head1 NOTES - -The letters B<i> and B<d> in for example B<i2d_X509> stand for -"internal" (that is an internal C structure) and "DER". So -B<i2d_X509> converts from internal to DER. 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 functions can also understand B<BER> forms. - -The actual X509 structure passed to i2d_X509() must be a valid -populated B<X509> structure it can B<not> simply be fed with an -empty structure such as that returned by X509_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 B<strlen()> will B<not> return the correct length -of the encoded structure. - -The ways that B<*in> and B<*out> are incremented after the operation -can trap the unwary. See the B<WARNINGS> section for some common -errors. - -The reason for the auto increment behaviour is to reflect a typical -usage of ASN1 functions: after one structure is encoded or decoded -another will processed after it. - -=head1 EXAMPLES - -Allocate and encode the DER encoding of an X509 structure: - - int len; - unsigned char *buf, *p; - - len = i2d_X509(x, NULL); - - buf = OPENSSL_malloc(len); - - if (buf == NULL) - /* error */ - - p = buf; - - i2d_X509(x, &p); - -If you are using OpenSSL 0.9.7 or later then this can be -simplified to: - - - 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; - - /* Something to setup buf and len */ - - p = buf; - - x = d2i_X509(NULL, &p, len); - - if (x == NULL) - /* Some error */ - -Alternative technique: - - X509 *x; - - unsigned char *buf, *p; - - int len; - - /* Something to setup buf and len */ - - p = buf; - - x = NULL; - - if(!d2i_X509(&x, &p, len)) - /* Some error */ - - -=head1 WARNINGS - -The use of 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); - - if (buf == NULL) - /* error */ - - i2d_X509(x, &buf); - - /* Other stuff ... */ - - 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 B<OPENSSL_malloc()> -and the subsequent call to B<OPENSSL_free()> may well crash. - -The auto allocation feature (setting buf to NULL) only works on OpenSSL -0.9.7 and later. Attempts to use it on earlier versions will typically -cause a segmentation violation. - -Another trap to avoid is misuse of the B<xp> argument to B<d2i_X509()>: - - X509 *x; - - if (!d2i_X509(&x, &p, len)) - /* Some error */ - -This will probably crash somewhere in B<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_X509() 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_X509() 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_X509(). This may be -fixed in future so code should not assume that i2d_X509() will -always succeed. - -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. - -Any function which encodes an X509 structure such as i2d_X509(), -i2d_X509_fp() or i2d_X509_bio() may return a stale encoding if the -B<X509> structure has been modified after deserialization or previous -serialization. - -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 RETURN VALUES - -d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure -or B<NULL> if an error occurs. The error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used -with a valid X509 structure being passed in via B<px> then the object is not -freed in the event of error but may be in a potentially invalid or inconsistent -state. - -i2d_X509() returns the number of bytes successfully encoded or a negative -value if an error occurs. The error code can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. - -i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error -occurs The error code can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp -are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/d2i_X509_ALGOR.pod b/openssl/doc/crypto/d2i_X509_ALGOR.pod deleted file mode 100644 index 9e5cd92..0000000 --- a/openssl/doc/crypto/d2i_X509_ALGOR.pod +++ /dev/null @@ -1,30 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length); - int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an B<X509_ALGOR> structure which is -equivalent to the B<AlgorithmIdentifier> structure. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/d2i_X509_CRL.pod b/openssl/doc/crypto/d2i_X509_CRL.pod deleted file mode 100644 index 675d38b..0000000 --- a/openssl/doc/crypto/d2i_X509_CRL.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_X509_CRL_fp, -i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_CRL *d2i_X509_CRL(X509_CRL **a, const unsigned char **pp, long length); - int i2d_X509_CRL(X509_CRL *a, unsigned char **pp); - - X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x); - X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x); - - int i2d_X509_CRL_bio(BIO *bp, X509_CRL *x); - int i2d_X509_CRL_fp(FILE *fp, X509_CRL *x); - -=head1 DESCRIPTION - -These functions decode and encode an X509 CRL (certificate revocation -list). - -Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/d2i_X509_NAME.pod b/openssl/doc/crypto/d2i_X509_NAME.pod deleted file mode 100644 index b025de7..0000000 --- a/openssl/doc/crypto/d2i_X509_NAME.pod +++ /dev/null @@ -1,31 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length); - int i2d_X509_NAME(X509_NAME *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an B<X509_NAME> structure which is the -same as the B<Name> type defined in RFC2459 (and elsewhere) and used -for example in certificate subject and issuer names. - -Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/d2i_X509_REQ.pod b/openssl/doc/crypto/d2i_X509_REQ.pod deleted file mode 100644 index 91c0c19..0000000 --- a/openssl/doc/crypto/d2i_X509_REQ.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp, -i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_REQ *d2i_X509_REQ(X509_REQ **a, const unsigned char **pp, long length); - int i2d_X509_REQ(X509_REQ *a, unsigned char **pp); - - X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x); - X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x); - - int i2d_X509_REQ_bio(BIO *bp, X509_REQ *x); - int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x); - -=head1 DESCRIPTION - -These functions decode and encode a PKCS#10 certificate request. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/d2i_X509_SIG.pod b/openssl/doc/crypto/d2i_X509_SIG.pod deleted file mode 100644 index e48fd79..0000000 --- a/openssl/doc/crypto/d2i_X509_SIG.pod +++ /dev/null @@ -1,30 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length); - int i2d_X509_SIG(X509_SIG *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an X509_SIG structure which is -equivalent to the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/openssl/doc/crypto/des.pod b/openssl/doc/crypto/des.pod deleted file mode 100644 index e1add56..0000000 --- a/openssl/doc/crypto/des.pod +++ /dev/null @@ -1,357 +0,0 @@ -=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_cbcm_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_enc_read, DES_enc_write - 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_cbcm_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *ks1, DES_key_schedule *ks2, - DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2, - 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); - - int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched, - DES_cblock *iv); - int DES_enc_write(int fd, const void *buf, int len, - DES_key_schedule *sched, DES_cblock *iv); - -=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)|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 week 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)|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 emulates the normal non-thread safe semantics -of crypt(3). - -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. - -DES_enc_read() is used to read I<len> bytes from file descriptor -I<fd> into buffer I<buf>. The data being read from I<fd> is assumed to -have come from DES_enc_write() and is decrypted using I<sched> for -the key schedule and I<iv> for the initial vector. - -B<Warning:> The data format used by DES_enc_write() and DES_enc_read() -has a cryptographic weakness: When asked to write more than MAXWRITE -bytes, DES_enc_write() will split the data into several chunks that -are all encrypted using the same IV. So don't use these functions -unless you are sure you know what you do (in which case you might not -want to use them anyway). They cannot handle non-blocking sockets. -DES_enc_read() uses an internal state and thus cannot be used on -multiple files. - -I<DES_rw_mode> is used to specify the encryption mode to use with -DES_enc_read() and DES_end_write(). If set to I<DES_PCBC_MODE> (the -default), DES_pcbc_encrypt is used. If set to I<DES_CBC_MODE> -DES_cbc_encrypt is used. - -=head1 NOTES - -Single-key DES is insecure due to its short key size. ECB mode is -not suitable for most applications; see L<des_modes(7)|des_modes(7)>. - -The L<evp(3)|evp(3)> library provides higher-level encryption functions. - -=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 CONFORMING TO - -ANSI X3.106 - -The B<des> library was written to be source code compatible with -the MIT Kerberos library. - -=head1 SEE ALSO - -crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)> - -=head1 HISTORY - -In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid -clashes with older versions of libdes. Compatibility des_ functions -are provided for a short while, as well as crypt(). -Declarations for these are in <openssl/des_old.h>. There is no DES_ -variant for des_random_seed(). -This will happen to other functions -as well if they are deemed redundant (des_random_seed() just calls -RAND_seed() and is present for backward compatibility only), buggy or -already scheduled for removal. - -des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(), -des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(), -des_quad_cksum(), des_random_key() and des_string_to_key() -are available in the MIT Kerberos library; -des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key() -are available in newer versions of that library. - -des_set_key_checked() and des_set_key_unchecked() were added in -OpenSSL 0.9.5. - -des_generate_random_block(), des_init_random_number_generator(), -des_new_random_key(), des_set_random_generator_seed() and -des_set_sequence_number() and des_rand_data() are used in newer -versions of Kerberos but are not implemented here. - -des_random_key() generated cryptographically weak random data in -SSLeay and in OpenSSL prior version 0.9.5, as well as in the original -MIT library. - -=head1 AUTHOR - -Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/openssl/doc/crypto/des_modes.pod b/openssl/doc/crypto/des_modes.pod deleted file mode 100644 index e883ca8..0000000 --- a/openssl/doc/crypto/des_modes.pod +++ /dev/null @@ -1,255 +0,0 @@ -=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 2 - -=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 2 - -=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 2 - -=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 2 - - -=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 2 - -=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 2 - - -=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<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<idea(3)|idea(3)>, -L<rc2(3)|rc2(3)> - -=cut - diff --git a/openssl/doc/crypto/dh.pod b/openssl/doc/crypto/dh.pod deleted file mode 100644 index c3ccd06..0000000 --- a/openssl/doc/crypto/dh.pod +++ /dev/null @@ -1,78 +0,0 @@ -=pod - -=head1 NAME - -dh - Diffie-Hellman key agreement - -=head1 SYNOPSIS - - #include <openssl/dh.h> - #include <openssl/engine.h> - - DH * DH_new(void); - void DH_free(DH *dh); - - int DH_size(const DH *dh); - - DH * DH_generate_parameters(int prime_len, int generator, - void (*callback)(int, int, void *), void *cb_arg); - int DH_check(const DH *dh, int *codes); - - int DH_generate_key(DH *dh); - int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); - - 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); - - int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int DH_set_ex_data(DH *d, int idx, char *arg); - char *DH_get_ex_data(DH *d, int idx); - - DH * d2i_DHparams(DH **a, unsigned char **pp, long length); - int i2d_DHparams(const DH *a, unsigned char **pp); - - int DHparams_print_fp(FILE *fp, const DH *x); - int DHparams_print(BIO *bp, const DH *x); - -=head1 DESCRIPTION - -These functions implement the Diffie-Hellman key agreement protocol. -The generation of shared DH parameters is described in -L<DH_generate_parameters(3)|DH_generate_parameters(3)>; L<DH_generate_key(3)|DH_generate_key(3)> describes how -to perform a key agreement. - -The B<DH> structure consists of several BIGNUM components. - - struct - { - BIGNUM *p; // prime number (shared) - BIGNUM *g; // generator of Z_p (shared) - BIGNUM *priv_key; // private DH value x - BIGNUM *pub_key; // public DH value g^x - // ... - }; - DH - -Note that DH keys may use non-standard B<DH_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using DH -structure elements directly and instead use API functions to query or -modify keys. - -=head1 SEE ALSO - -L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, -L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>, -L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>, -L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>, -L<DH_generate_parameters(3)|DH_generate_parameters(3)>, -L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>, -L<RSA_print(3)|RSA_print(3)> - -=cut diff --git a/openssl/doc/crypto/dsa.pod b/openssl/doc/crypto/dsa.pod deleted file mode 100644 index da07d2b..0000000 --- a/openssl/doc/crypto/dsa.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -dsa - Digital Signature Algorithm - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - #include <openssl/engine.h> - - DSA * DSA_new(void); - void DSA_free(DSA *dsa); - - int DSA_size(const DSA *dsa); - - 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); - - DH * DSA_dup_DH(const DSA *r); - - int DSA_generate_key(DSA *dsa); - - int DSA_sign(int dummy, 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 dummy, const unsigned char *dgst, int len, - const unsigned char *sigbuf, int siglen, DSA *dsa); - - 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); - const DSA_METHOD *DSA_OpenSSL(void); - - int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int DSA_set_ex_data(DSA *d, int idx, char *arg); - char *DSA_get_ex_data(DSA *d, int idx); - - DSA_SIG *DSA_SIG_new(void); - void DSA_SIG_free(DSA_SIG *a); - int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); - DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); - - 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); - - DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); - DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); - DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); - int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - int i2d_DSAparams(const DSA *a,unsigned char **pp); - - int DSAparams_print(BIO *bp, const DSA *x); - int DSAparams_print_fp(FILE *fp, const DSA *x); - int DSA_print(BIO *bp, const DSA *x, int off); - int DSA_print_fp(FILE *bp, const DSA *x, int off); - -=head1 DESCRIPTION - -These functions implement the Digital Signature Algorithm (DSA). The -generation of shared DSA parameters is described in -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>; -L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to -generate a signature key. Signature generation and verification are -described in L<DSA_sign(3)|DSA_sign(3)>. - -The B<DSA> structure consists of several BIGNUM components. - - struct - { - BIGNUM *p; // prime number (public) - BIGNUM *q; // 160-bit subprime, q | p-1 (public) - BIGNUM *g; // generator of subgroup (public) - BIGNUM *priv_key; // private key x - BIGNUM *pub_key; // public key y = g^x - // ... - } - DSA; - -In public keys, B<priv_key> is NULL. - -Note that DSA keys may use non-standard B<DSA_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using DSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS 186 (Digital Signature -Standard, DSS), ANSI X9.30 - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, -L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<engine(3)|engine(3)>, -L<DSA_new(3)|DSA_new(3)>, -L<DSA_size(3)|DSA_size(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, -L<DSA_dup_DH(3)|DSA_dup_DH(3)>, -L<DSA_generate_key(3)|DSA_generate_key(3)>, -L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>, -L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, -L<RSA_print(3)|RSA_print(3)> - -=cut diff --git a/openssl/doc/crypto/ec.pod b/openssl/doc/crypto/ec.pod deleted file mode 100644 index 7d57ba8..0000000 --- a/openssl/doc/crypto/ec.pod +++ /dev/null @@ -1,201 +0,0 @@ -=pod - -=head1 NAME - -ec - Elliptic Curve functions - -=head1 SYNOPSIS - - #include <openssl/ec.h> - #include <openssl/bn.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); - - EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); - void EC_GROUP_free(EC_GROUP *group); - void EC_GROUP_clear_free(EC_GROUP *group); - 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_METHOD_get_field_type(const EC_METHOD *meth); - 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); - int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); - 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_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); - 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); - 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); - - size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); - - 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); - 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 *, const EC_POINT *, - point_conversion_form_t form, BIGNUM *, BN_CTX *); - EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, - EC_POINT *, BN_CTX *); - char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BN_CTX *); - EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, - EC_POINT *, BN_CTX *); - - 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); - - 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); - EC_GROUP *d2i_ECPKParameters(EC_GROUP **, const unsigned char **in, long len); - int i2d_ECPKParameters(const EC_GROUP *, unsigned char **out); - #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) - #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) - #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ - (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) - #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ - (unsigned char *)(x)) - int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); - int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); - - 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); - unsigned EC_KEY_get_enc_flags(const EC_KEY *key); - void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); - 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_get_key_method_data(EC_KEY *key, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - 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); - - EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); - - EC_KEY *d2i_ECParameters(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECParameters(EC_KEY *key, unsigned char **out); - - EC_KEY *o2i_ECPublicKey(EC_KEY **key, const unsigned char **in, long len); - int i2o_ECPublicKey(EC_KEY *key, unsigned char **out); - int ECParameters_print(BIO *bp, const EC_KEY *key); - int EC_KEY_print(BIO *bp, const EC_KEY *key, int off); - int ECParameters_print_fp(FILE *fp, const EC_KEY *key); - int EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off); - #define ECParameters_dup(x) ASN1_dup_of(EC_KEY,i2d_ECParameters,d2i_ECParameters,x) - #define EVP_PKEY_CTX_set_ec_paramgen_curve_nid(ctx, nid) \ - EVP_PKEY_CTX_ctrl(ctx, EVP_PKEY_EC, EVP_PKEY_OP_PARAMGEN, \ - EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID, nid, NULL) - - -=head1 DESCRIPTION - -This library provides an extensive set of functions for performing operations on elliptic curves over finite fields. -In general an elliptic curve is one with an equation of the form: - -y^2 = x^3 + ax + b - -An B<EC_GROUP> structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an -B<EC_POINT> structure. An B<EC_KEY> is used to hold a private/public key pair, where a private key is simply a BIGNUM and a -public key is a point on a curve (represented by an B<EC_POINT>). - -The library contains a number of alternative implementations of the different functions. Each implementation is optimised -for different scenarios. No matter which implementation is being used, the interface remains the same. The library -handles calling the correct implementation when an interface function is invoked. An implementation is represented by -an B<EC_METHOD> structure. - -The creation and destruction of B<EC_GROUP> objects is described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>. Functions for -manipulating B<EC_GROUP> objects are described in L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>. - -Functions for creating, destroying and manipulating B<EC_POINT> objects are explained in L<EC_POINT_new(3)|EC_POINT_new(3)>, -whilst functions for performing mathematical operations and tests on B<EC_POINTs> are coverd in L<EC_POINT_add(3)|EC_POINT_add(3)>. - -For working with private and public keys refer to L<EC_KEY_new(3)|EC_KEY_new(3)>. Implementations are covered in -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>. - -For information on encoding and decoding curve parameters to and from ASN1 see L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> - - -=cut diff --git a/openssl/doc/crypto/ecdsa.pod b/openssl/doc/crypto/ecdsa.pod deleted file mode 100644 index 46c071b..0000000 --- a/openssl/doc/crypto/ecdsa.pod +++ /dev/null @@ -1,206 +0,0 @@ -=pod - -=head1 NAME - -ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify - Elliptic Curve Digital Signature Algorithm - -=head1 SYNOPSIS - - #include <openssl/ecdsa.h> - - ECDSA_SIG* ECDSA_SIG_new(void); - void ECDSA_SIG_free(ECDSA_SIG *sig); - 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); - - ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len, - 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_do_verify(const unsigned char *dgst, int dgst_len, - const ECDSA_SIG *sig, EC_KEY* eckey); - int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, - BIGNUM **kinv, BIGNUM **rp); - int ECDSA_sign(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, EC_KEY *eckey); - 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); - int ECDSA_verify(int type, const unsigned char *dgst, - int dgstlen, const unsigned char *sig, - int siglen, EC_KEY *eckey); - int ECDSA_size(const EC_KEY *eckey); - - const ECDSA_METHOD* ECDSA_OpenSSL(void); - void ECDSA_set_default_method(const ECDSA_METHOD *meth); - const ECDSA_METHOD* ECDSA_get_default_method(void); - int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); - - int ECDSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg); - void* ECDSA_get_ex_data(EC_KEY *d, int idx); - -=head1 DESCRIPTION - -The B<ECDSA_SIG> structure consists of two BIGNUMs for the -r and s value of a ECDSA signature (see X9.62 or FIPS 186-2). - - struct - { - BIGNUM *r; - BIGNUM *s; - } ECDSA_SIG; - -ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this -function also allocates the BIGNUMs) and initialize it. - -ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>. - -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 B<i2d_ECDSA_SIG> returns the expected length in bytes of -the DER encoded signature). B<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_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 B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>. - -ECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv> -and B<rp> set to NULL. - -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 signatures is -stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> -must point to B<ECDSA_size> bytes of memory. The parameter B<type> -is ignored. - -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_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv> -and B<rp> set to NULL. - -ECDSA_do_sign_ex() computes a digital signature of the B<dgst_len> -bytes hash value B<dgst> using the private key B<eckey> and the -optional pre-computed values B<kinv> and B<rp>. The signature is -returned in a newly allocated B<ECDSA_SIG> structure (or NULL on error). - -ECDSA_do_verify() verifies that the signature B<sig> is a valid -ECDSA signature of the hash value B<dgst> of size B<dgst_len> -using the public key B<eckey>. - -=head1 RETURN VALUES - -ECDSA_size() returns the maximum length signature or 0 on error. - -ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0 -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)|ERR_get_error(3)>. - -=head1 EXAMPLES - -Creating a ECDSA signature of given SHA-1 hash value using the -named curve secp192k1. - -First step: create a 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_secp192k1); - if (eckey == NULL) - { - /* error */ - } - if (!EC_KEY_generate_key(eckey)) - { - /* error */ - } - -Second step: compute the ECDSA signature of a SHA-1 hash value -using B<ECDSA_do_sign> - - sig = ECDSA_do_sign(digest, 20, eckey); - if (sig == NULL) - { - /* error */ - } - -or using B<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); - { - /* error */ - } - -Third step: verify the created ECDSA signature using B<ECDSA_do_verify> - - ret = ECDSA_do_verify(digest, 20, sig, eckey); - -or using B<ECDSA_verify> - - ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); - -and finally evaluate the return value: - - if (ret == -1) - { - /* error */ - } - else if (ret == 0) - { - /* incorrect signature */ - } - else /* ret == 1 */ - { - /* signature ok */ - } - -=head1 CONFORMING TO - -ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 -(Digital Signature Standard, DSS) - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)> - -=head1 HISTORY - -The ecdsa implementation was first introduced in OpenSSL 0.9.8 - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/openssl/doc/crypto/engine.pod b/openssl/doc/crypto/engine.pod deleted file mode 100644 index 48741ee..0000000 --- a/openssl/doc/crypto/engine.pod +++ /dev/null @@ -1,599 +0,0 @@ -=pod - -=head1 NAME - -engine - 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_openssl(void); - void ENGINE_load_dynamic(void); - #ifndef OPENSSL_NO_STATIC_ENGINE - void ENGINE_load_4758cca(void); - void ENGINE_load_aep(void); - void ENGINE_load_atalla(void); - void ENGINE_load_chil(void); - void ENGINE_load_cswift(void); - void ENGINE_load_gmp(void); - void ENGINE_load_nuron(void); - void ENGINE_load_sureware(void); - void ENGINE_load_ubsec(void); - #endif - void ENGINE_load_cryptodev(void); - void ENGINE_load_builtin_engines(void); - - void ENGINE_cleanup(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_STORE(ENGINE *e); - void ENGINE_unregister_STORE(ENGINE *e); - void ENGINE_register_all_STORE(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); - - int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); - void *ENGINE_get_ex_data(const ENGINE *e, int idx); - - int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); - - 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_STORE(ENGINE *e, const STORE_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); - const STORE_METHOD *ENGINE_get_STORE(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); - - void ENGINE_add_conf_module(void); - -=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, - STORE_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, eg. - - /* Make the "dynamic" ENGINE available */ - void ENGINE_load_dynamic(void); - /* Make the CryptoSwift hardware acceleration support available */ - void ENGINE_load_cswift(void); - /* Make support for nCipher's "CHIL" hardware available */ - void ENGINE_load_chil(void); - ... - /* Make ALL ENGINE implementations bundled with OpenSSL available */ - void ENGINE_load_builtin_engines(void); - -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 if any ENGINEs are loaded, even if they are never registered or -used, it is necessary to use the ENGINE_cleanup() function to -correspondingly cleanup before program exit, if the caller wishes to avoid -memory leaks. This mechanism uses 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 allows 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. - -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 the control -commands implemented by a given ENGINE, specifically the commands; - - #define ENGINE_HAS_CTRL_FUNCTION 10 - #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 - #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 - #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 - #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 - #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 - #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 - #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 - #define ENGINE_CTRL_GET_CMD_FLAGS 18 - -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; - - #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 - #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 - #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 - #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 - -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 determinie 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). - -=head2 Future developments - -The ENGINE API and internal architecture is currently being reviewed. Slated for -possible release in 0.9.8 is support for transparent loading of "dynamic" -ENGINEs (built as self-contained shared-libraries). This would allow ENGINE -implementations to be provided independently of OpenSSL libraries and/or -OpenSSL-based applications, and would also remove any requirement for -applications to explicitly use the "dynamic" ENGINE to bind to shared-library -implementations. - -=head1 SEE ALSO - -L<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)> - -=cut diff --git a/openssl/doc/crypto/err.pod b/openssl/doc/crypto/err.pod deleted file mode 100644 index 4a5dc69..0000000 --- a/openssl/doc/crypto/err.pod +++ /dev/null @@ -1,186 +0,0 @@ -=pod - -=head1 NAME - -err - error codes - -=head1 SYNOPSIS - - #include <openssl/err.h> - - unsigned long ERR_get_error(void); - unsigned long ERR_peek_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_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); - - int ERR_GET_LIB(unsigned long e); - int ERR_GET_FUNC(unsigned long e); - int ERR_GET_REASON(unsigned long e); - - void ERR_clear_error(void); - - char *ERR_error_string(unsigned long e, char *buf); - 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); - - void ERR_print_errors(BIO *bp); - void ERR_print_errors_fp(FILE *fp); - - void ERR_load_crypto_strings(void); - void ERR_free_strings(void); - - void ERR_remove_state(unsigned long pid); - - void ERR_put_error(int lib, int func, int reason, const char *file, - int line); - void ERR_add_error_data(int num, ...); - - void ERR_load_strings(int lib,ERR_STRING_DATA str[]); - unsigned long ERR_PACK(int lib, int func, int reason); - int ERR_get_next_error_library(void); - -=head1 DESCRIPTION - -When a call to the OpenSSL library fails, this is usually signalled -by the return value, and an error code is stored in an error queue -associated with the current thread. The B<err> library provides -functions to obtain these error codes and textual error messages. - -The L<ERR_get_error(3)|ERR_get_error(3)> manpage describes how to -access error codes. - -Error codes contain information about where the error occurred, and -what went wrong. L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> describes how to -extract this information. A method to obtain human-readable error -messages is described in L<ERR_error_string(3)|ERR_error_string(3)>. - -L<ERR_clear_error(3)|ERR_clear_error(3)> can be used to clear the -error queue. - -Note that L<ERR_remove_state(3)|ERR_remove_state(3)> should be used to -avoid memory leaks when threads are terminated. - -=head1 ADDING NEW ERROR CODES TO OPENSSL - -See L<ERR_put_error(3)> if you want to record error codes in the -OpenSSL error system from within your application. - -The remainder of this section is of interest only if you want to add -new error codes to OpenSSL or add error codes from external libraries. - -=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 ssl23_read() reports a -"handshake failure" as follows: - - SSLerr(SSL_F_SSL23_READ, 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 "SSL23_READ" in the above example. - -The trailing section of a reason code (after the "_R_") is translated -into lower case and underscores changed to spaces. - -When you are using new function or reason codes, run B<make errors>. -The necessary B<#define>s will then automatically be added to the -sub-library's header file. - -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. - -=head2 Adding new libraries - -When adding a new sub-library to OpenSSL, assign it a library number -B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its -name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add -C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function -(in B<crypto/err/err_all.c>). Finally, add an entry - - L XXX xxx.h xxx_err.c - -to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile. -Running B<make errors> will then generate a file B<xxx_err.c>, and -add all error codes used in the library to B<xxx.h>. - -Additionally the library include file must have a certain form. -Typically it will initially look like this: - - #ifndef HEADER_XXX_H - #define HEADER_XXX_H - - #ifdef __cplusplus - extern "C" { - #endif - - /* Include files */ - - #include <openssl/bio.h> - #include <openssl/x509.h> - - /* Macros, structures and function prototypes */ - - - /* BEGIN ERROR CODES */ - -The B<BEGIN ERROR CODES> sequence is used by the error code -generation script as the point to place new error codes, any text -after this point will be overwritten when B<make errors> is run. -The closing #endif etc will be automatically added by the script. - -The generated C error code file B<xxx_err.c> will load the header -files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the -header file must load any additional header files containing any -definitions it uses. - -=head1 USING ERROR CODES IN EXTERNAL LIBRARIES - -It is also possible to use OpenSSL's error code scheme in external -libraries. The library needs to load its own codes and call the OpenSSL -error code insertion script B<mkerr.pl> explicitly to add codes to -the header file and generate the C error code file. This will normally -be done if the external library needs to generate new ASN1 structures -but it can also be used to add more general purpose error code handling. - -TBA more details - -=head1 INTERNALS - -The error queues are stored in a hash table with one B<ERR_STATE> -entry for each pid. ERR_get_state() returns the current thread's -B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error -codes. When more error codes are added, the old ones are overwritten, -on the assumption that the most recent errors are most important. - -Error strings are also stored in hash table. The hash tables can -be obtained by calling ERR_get_err_state_table(void) and -ERR_get_string_table(void) respectively. - -=head1 SEE ALSO - -L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>, -L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>, -L<ERR_clear_error(3)|ERR_clear_error(3)>, -L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_print_errors(3)|ERR_print_errors(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<ERR_remove_state(3)|ERR_remove_state(3)>, -L<ERR_put_error(3)|ERR_put_error(3)>, -L<ERR_load_strings(3)|ERR_load_strings(3)>, -L<SSL_get_error(3)|SSL_get_error(3)> - -=cut diff --git a/openssl/doc/crypto/evp.pod b/openssl/doc/crypto/evp.pod deleted file mode 100644 index 303cd95..0000000 --- a/openssl/doc/crypto/evp.pod +++ /dev/null @@ -1,108 +0,0 @@ -=pod - -=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_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)|EVP_PKEY_set1_RSA(3)> page, or -new keys can be generated using L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>. -EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)|EVP_PKEY_cmp(3)>, or printed using -L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>. - -The EVP_PKEY functions support the full range of asymmetric algorithm operations: - -=over - -=item For key agreement see L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> - -=item For signing and verifying see L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)|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<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> -functions for this purpose. - -=item For encryption and decryption see L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)> -and L<EVP_PKEY_decrypt(3)|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<B<EVP_Seal>I<...>|EVP_SealInit(3)> and -L<B<EVP_Open>I<...>|EVP_OpenInit(3)> functions. - -=back - -The L<EVP_BytesToKey(3)|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. - -Algorithms are loaded with L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>. - -All the symmetric algorithms (ciphers), digests and asymmetric algorithms -(public key algorithms) can be replaced by L<ENGINE|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)|EVP_DigestInit(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_OpenInit(3)|EVP_OpenInit(3)>, -L<EVP_SealInit(3)|EVP_SealInit(3)>, -L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, -L<EVP_SignInit(3)|EVP_SignInit(3)>, -L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, -L<EVP_EncodeInit(3)>, -L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>, -L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>, -L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>, -L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>, -L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>, -L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>, -L<engine(3)|engine(3)> - -=cut diff --git a/openssl/doc/crypto/hmac.pod b/openssl/doc/crypto/hmac.pod deleted file mode 100644 index 2c8f20a..0000000 --- a/openssl/doc/crypto/hmac.pod +++ /dev/null @@ -1,110 +0,0 @@ -=pod - -=head1 NAME - -HMAC, HMAC_CTX_init, HMAC_Init, HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_CTX_cleanup, -HMAC_cleanup - 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); - - void HMAC_CTX_init(HMAC_CTX *ctx); - - int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md); - 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_cleanup(HMAC_CTX *ctx); - void HMAC_cleanup(HMAC_CTX *ctx); - -=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>. - -B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. - -HMAC_CTX_init() initialises a B<HMAC_CTX> before first use. It must be -called. - -HMAC_CTX_cleanup() erases the key and other data from the B<HMAC_CTX> -and releases any associated resources. It must be called when an -B<HMAC_CTX> is no longer required. - -HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back -compatibility with 0.9.6b, it is deprecated. - -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<NB: 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. - -=head1 RETURN VALUES - -HMAC() returns a pointer to the message authentication code or NULL if -an error occurred. - -HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if -an error occurred. - -HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values. - -=head1 CONFORMING TO - -RFC 2104 - -=head1 SEE ALSO - -L<sha(3)|sha(3)>, L<evp(3)|evp(3)> - -=head1 HISTORY - -HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() -are available since SSLeay 0.9.0. - -HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available -since OpenSSL 0.9.7. - -HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in -versions of OpenSSL before 1.0.0. - -=cut diff --git a/openssl/doc/crypto/i2d_CMS_bio_stream.pod b/openssl/doc/crypto/i2d_CMS_bio_stream.pod deleted file mode 100644 index 558bdd0..0000000 --- a/openssl/doc/crypto/i2d_CMS_bio_stream.pod +++ /dev/null @@ -1,44 +0,0 @@ -=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)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> -L<CMS_decrypt(3)|CMS_decrypt(3)>, -L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>, -L<PEM_write_bio_CMS_stream(3)|PEM_write_bio_CMS_stream(3)> - -=head1 HISTORY - -i2d_CMS_bio_stream() was added to OpenSSL 1.0.0 - -=cut diff --git a/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod b/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod deleted file mode 100644 index a37231e..0000000 --- a/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod +++ /dev/null @@ -1,44 +0,0 @@ -=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)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, -L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, -L<PEM_write_bio_PKCS7_stream(3)|PEM_write_bio_PKCS7_stream(3)> - -=head1 HISTORY - -i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0 - -=cut diff --git a/openssl/doc/crypto/lh_stats.pod b/openssl/doc/crypto/lh_stats.pod deleted file mode 100644 index 3eeaa72..0000000 --- a/openssl/doc/crypto/lh_stats.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, -lh_node_stats_bio, lh_node_usage_stats_bio - LHASH statistics - -=head1 SYNOPSIS - - #include <openssl/lhash.h> - - void lh_stats(LHASH *table, FILE *out); - void lh_node_stats(LHASH *table, FILE *out); - void lh_node_usage_stats(LHASH *table, FILE *out); - - void lh_stats_bio(LHASH *table, BIO *out); - void lh_node_stats_bio(LHASH *table, BIO *out); - void 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. - -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. - -lh_node_stats() prints the number of entries for each 'bucket' in the -hash table. - -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. - -lh_stats_bio(), lh_node_stats_bio() and 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)|bio(3)>, L<lhash(3)|lhash(3)> - -=head1 HISTORY - -These functions are available in all versions of SSLeay and OpenSSL. - -This manpage is derived from the SSLeay documentation. - -=cut diff --git a/openssl/doc/crypto/lhash.pod b/openssl/doc/crypto/lhash.pod deleted file mode 100644 index 73a19b6..0000000 --- a/openssl/doc/crypto/lhash.pod +++ /dev/null @@ -1,302 +0,0 @@ -=pod - -=head1 NAME - -lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error - dynamic hash table - -=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_OF<type> *table, <type> *data); - - void lh_<type>_doall(LHASH_OF(<type> *table, LHASH_DOALL_FN_TYPE func); - void lh_<type>_doall_arg(LHASH_OF(<type> *table, LHASH_DOALL_ARG_FN_TYPE func, - <type2>, <type2> *arg); - - int lh_<type>_error(LHASH_OF(<type> *table); - - typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); - typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_FN_TYPE)(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. - -lh_<type>_new() creates a new B<LHASH_OF(<type>> structure to store -arbitrary data entries, and provides 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<DECLARE_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(). These provide per-variable casts before calling the -type-specific callbacks written by the application author. These -macros, as well as those used for the "doall" callbacks, are defined -as; - - #define DECLARE_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *); - #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *arg) { \ - const o_type *a = arg; \ - return name##_hash(a); } - #define LHASH_HASH_FN(name) name##_LHASH_HASH - - #define DECLARE_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *, const void *); - #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *arg1, const void *arg2) { \ - const o_type *a = arg1; \ - const o_type *b = arg2; \ - return name##_cmp(a,b); } - #define LHASH_COMP_FN(name) name##_LHASH_COMP - - #define DECLARE_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *); - #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *arg) { \ - o_type *a = arg; \ - name##_doall(a); } - #define LHASH_DOALL_FN(name) name##_LHASH_DOALL - - #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *, void *); - #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \ - o_type *a = arg1; \ - a_type *b = arg2; \ - name##_doall_arg(a, b); } - #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG - - An example of a hash table storing (pointers to) structures of type 'STUFF' - could be defined as follows; - - /* Calculates the hash value of 'tohash' (implemented elsewhere) */ - unsigned long STUFF_hash(const STUFF *tohash); - /* Orders 'arg1' and 'arg2' (implemented elsewhere) */ - int stuff_cmp(const STUFF *arg1, const STUFF *arg2); - /* Create the type-safe wrapper functions for use in the LHASH internals */ - static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF); - static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF); - /* ... */ - int main(int argc, char *argv[]) { - /* Create the new hash table using the hash/compare wrappers */ - LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash), - LHASH_COMP_FN(STUFF_cmp)); - /* ... */ - } - -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 lh_<type>_doall() -and lh_<type>_doall_arg(), function pointer casting should be avoided -in the callbacks (see B<NOTE>) - instead use the declare/implement -macros to create type-checked wrappers that cast variables prior to -calling your type-specific callbacks. An example of this is -illustrated here where the callback is used to cleanup resources for -items in the hash table prior to the hashtable itself being -deallocated: - - /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ - void STUFF_cleanup_doall(STUFF *a); - /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ - IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF) - /* ... then later in the code ... */ - /* So to run "STUFF_cleanup" against all items in a hash table ... */ - lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); - /* Then the hash table itself can be deallocated */ - lh_STUFF_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 STUFF_print_doall_arg(const STUFF *a, BIO *output_bio); - /* Implement a prototype-compatible wrapper for "STUFF_print" */ - static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO) - /* ... then later in the code ... */ - /* Print out the entire hashtable to a particular BIO */ - lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, - logging_bio); - -lh_<type>_error() can be used to determine if an error occurred in the last -operation. lh_<type>_error() is a macro. - -=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 "STUFF_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 INTERNALS - -The following description is based on the SSLeay documentation: - -The B<lhash> library implements a hash table described in the -I<Communications of the ACM> in 1991. What makes this hash table -different is that as the table fills, the hash table is increased (or -decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of -all hashes being redistributed over twice as many 'buckets', one -bucket is split. So when an 'expand' is done, there is only a minimal -cost to redistribute some values. Subsequent inserts will cause more -single 'bucket' redistributions but there will never be a sudden large -cost due to redistributing all the 'buckets'. - -The state for a particular hash table is kept in the B<LHASH> structure. -The decision to increase or decrease the hash table size is made -depending on the 'load' of the hash table. The load is the number of -items in the hash table divided by the size of the hash table. The -default values are as follows. If (hash->up_load E<lt> load) =E<gt> -expand. if (hash-E<gt>down_load E<gt> load) =E<gt> contract. The -B<up_load> has a default value of 1 and B<down_load> has a default value -of 2. These numbers can be modified by the application by just -playing with the B<up_load> and B<down_load> variables. The 'load' is -kept in a form which is multiplied by 256. So -hash-E<gt>up_load=8*256; will cause a load of 8 to be set. - -If you are interested in performance the field to watch is -num_comp_calls. The hash library keeps track of the 'hash' value for -each item so when a lookup is done, the 'hashes' are compared, if -there is a match, then a full compare is done, and -hash-E<gt>num_comp_calls is incremented. If num_comp_calls is not equal -to num_delete plus num_retrieve it means that your hash function is -generating hashes that are the same for different values. It is -probably worth changing your hash function if this is the case because -even if your hash table has 10 items in a 'bucket', it can be searched -with 10 B<unsigned long> compares and 10 linked list traverses. This -will be much less expensive that 10 calls to your compare function. - -lh_strhash() is a demo string hashing function: - - unsigned long lh_strhash(const char *c); - -Since the B<LHASH> routines would normally be passed structures, this -routine would not normally be passed to lh_<type>_new(), rather it would be -used in the function passed to lh_<type>_new(). - -=head1 SEE ALSO - -L<lh_stats(3)|lh_stats(3)> - -=head1 HISTORY - -The B<lhash> library is available in all versions of SSLeay and OpenSSL. -lh_error() was added in SSLeay 0.9.1b. - -This manpage is derived from the SSLeay documentation. - -In OpenSSL 0.9.7, all lhash functions that were passed function pointers -were changed for better type safety, and the function types LHASH_COMP_FN_TYPE, -LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE -became available. - -In OpenSSL 1.0.0, the lhash interface was revamped for even better -type checking. - -=cut diff --git a/openssl/doc/crypto/md5.pod b/openssl/doc/crypto/md5.pod deleted file mode 100644 index d11d5c3..0000000 --- a/openssl/doc/crypto/md5.pod +++ /dev/null @@ -1,101 +0,0 @@ -=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)|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<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), -MD5_Update() and MD5_Final() are available in all versions of SSLeay -and OpenSSL. - -MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and -above. - -=cut diff --git a/openssl/doc/crypto/mdc2.pod b/openssl/doc/crypto/mdc2.pod deleted file mode 100644 index 41f648a..0000000 --- a/openssl/doc/crypto/mdc2.pod +++ /dev/null @@ -1,64 +0,0 @@ -=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)|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<sha(3)|sha(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since -SSLeay 0.8. - -=cut diff --git a/openssl/doc/crypto/pem.pod b/openssl/doc/crypto/pem.pod deleted file mode 100644 index 763eb6f..0000000 --- a/openssl/doc/crypto/pem.pod +++ /dev/null @@ -1,503 +0,0 @@ -=pod - -=head1 NAME - -PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, -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_read_bio_NETSCAPE_CERT_SEQUENCE, -PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, -PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines - -=head1 SYNOPSIS - - #include <openssl/pem.h> - - 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_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); - - NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); - - int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *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 -"traditional" private key format and can handle both RSA and DSA -private keys. The read functions can additionally transparently -handle PKCS#8 format encrypted and unencrypted keys too. - -PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() -write a private key in an EVP_PKEY structure in PKCS#8 -EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption -algorithms. The B<cipher> argument specifies the encryption algorithm to -use: unlike all other PEM routines the encryption is applied at the -PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no -encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. - -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. It 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. It 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. - -The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate -Sequence using a NETSCAPE_CERT_SEQUENCE 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 an unencrypted private key to a FILE pointer: - - if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) - { - /* Error */ - } - -Write a private key (using traditional format) to a BIO using -triple DES encryption, the pass phrase is prompted for: - - if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) - { - /* Error */ - } - -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 the pass phrase "hello": - - key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); - if (key == NULL) - { - /* Error */ - } - -Read a private key from a BIO using a pass phrase callback: - - key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); - if (key == NULL) - { - /* Error */ - } - -Skeleton pass phrase callback: - - int pass_cb(char *buf, int size, int rwflag, void *u); - { - int len; - char *tmp; - /* We'd probably do something else if 'rwflag' is 1 */ - printf("Enter pass phrase for \"%s\"\n", u); - - /* get pass phrase, length 'len' into 'tmp' */ - tmp = "hello"; - len = strlen(tmp); - - if (len <= 0) return 0; - /* if too long, truncate */ - if (len > size) len = size; - memcpy(buf, tmp, len); - return len; - } - -=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 - -This 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 DEK-Info contains two comma separated pieces of information: -the encryption algorithm name as used by EVP_get_cipherbyname() and an 8 -byte B<salt> encoded as a set of hexadecimal digits. - -After this is the base64 encoded encrypted data. - -The encryption key is determined using EVP_BytesToKey(), using B<salt> and an -iteration count of 1. The IV used is the value of B<salt> and *not* the IV -returned by EVP_BytesToKey(). - -=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 SEE ALSO - -L<EVP_get_cipherbyname(3)|EVP_get_cipherbyname>, L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> diff --git a/openssl/doc/crypto/rand.pod b/openssl/doc/crypto/rand.pod deleted file mode 100644 index b754854..0000000 --- a/openssl/doc/crypto/rand.pod +++ /dev/null @@ -1,175 +0,0 @@ -=pod - -=head1 NAME - -rand - pseudo-random number generator - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - int RAND_set_rand_engine(ENGINE *engine); - - int RAND_bytes(unsigned char *buf, int num); - int RAND_pseudo_bytes(unsigned char *buf, int num); - - void RAND_seed(const void *buf, int num); - void RAND_add(const void *buf, int num, double entropy); - int RAND_status(void); - - int RAND_load_file(const char *file, long max_bytes); - int RAND_write_file(const char *file); - const char *RAND_file_name(char *file, size_t num); - - int RAND_egd(const char *path); - - void RAND_set_rand_method(const RAND_METHOD *meth); - const RAND_METHOD *RAND_get_rand_method(void); - RAND_METHOD *RAND_SSLeay(void); - - void RAND_cleanup(void); - - /* For Win32 only */ - void RAND_screen(void); - int RAND_event(UINT, WPARAM, LPARAM); - -=head1 DESCRIPTION - -Since the introduction of the ENGINE API, the recommended way of controlling -default implementations is by using the ENGINE API functions. The default -B<RAND_METHOD>, as set by RAND_set_rand_method() and returned by -RAND_get_rand_method(), is only used if no ENGINE has been set as the default -"rand" implementation. Hence, these two functions are no longer the recommended -way to control defaults. - -If an alternative B<RAND_METHOD> implementation is being used (either set -directly or as provided by an ENGINE module), then it is entirely responsible -for the generation and management of a cryptographically secure PRNG stream. The -mechanisms described below relate solely to the software PRNG implementation -built in to OpenSSL and used by default. - -These functions implement a cryptographically secure pseudo-random -number generator (PRNG). It is used by other library functions for -example to generate random keys, and applications can use it when they -need randomness. - -A cryptographic PRNG must be seeded with unpredictable data such as -mouse movements or keys pressed at random by the user. This is -described in L<RAND_add(3)|RAND_add(3)>. Its state can be saved in a seed file -(see L<RAND_load_file(3)|RAND_load_file(3)>) to avoid having to go through the -seeding process whenever the application is started. - -L<RAND_bytes(3)|RAND_bytes(3)> describes how to obtain random data from the -PRNG. - -=head1 INTERNALS - -The RAND_SSLeay() method implements a PRNG based on a cryptographic -hash function. - -The following description of its design is based on the SSLeay -documentation: - -First up I will state the things I believe I need for a good RNG. - -=over 4 - -=item 1 - -A good hashing algorithm to mix things up and to convert the RNG 'state' -to random numbers. - -=item 2 - -An initial source of random 'state'. - -=item 3 - -The state should be very large. If the RNG is being used to generate -4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). -If your RNG state only has 128 bits, you are obviously limiting the -search space to 128 bits, not 2048. I'm probably getting a little -carried away on this last point but it does indicate that it may not be -a bad idea to keep quite a lot of RNG state. It should be easier to -break a cipher than guess the RNG seed data. - -=item 4 - -Any RNG seed data should influence all subsequent random numbers -generated. This implies that any random seed data entered will have -an influence on all subsequent random numbers generated. - -=item 5 - -When using data to seed the RNG state, the data used should not be -extractable from the RNG state. I believe this should be a -requirement because one possible source of 'secret' semi random -data would be a private key or a password. This data must -not be disclosed by either subsequent random numbers or a -'core' dump left by a program crash. - -=item 6 - -Given the same initial 'state', 2 systems should deviate in their RNG state -(and hence the random numbers generated) over time if at all possible. - -=item 7 - -Given the random number output stream, it should not be possible to determine -the RNG state or the next random number. - -=back - -The algorithm is as follows. - -There is global state made up of a 1023 byte buffer (the 'state'), a -working hash value ('md'), and a counter ('count'). - -Whenever seed data is added, it is inserted into the 'state' as -follows. - -The input is chopped up into units of 20 bytes (or less for -the last block). Each of these blocks is run through the hash -function as follows: The data passed to the hash function -is the current 'md', the same number of bytes from the 'state' -(the location determined by in incremented looping index) as -the current 'block', the new key data 'block', and 'count' -(which is incremented after each use). -The result of this is kept in 'md' and also xored into the -'state' at the same locations that were used as input into the -hash function. I -believe this system addresses points 1 (hash function; currently -SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash -function and xor). - -When bytes are extracted from the RNG, the following process is used. -For each group of 10 bytes (or less), we do the following: - -Input into the hash function the local 'md' (which is initialized from -the global 'md' before any bytes are generated), the bytes that are to -be overwritten by the random bytes, and bytes from the 'state' -(incrementing looping index). From this digest output (which is kept -in 'md'), the top (up to) 10 bytes are returned to the caller and the -bottom 10 bytes are xored into the 'state'. - -Finally, after we have finished 'num' random bytes for the caller, -'count' (which is incremented) and the local and global 'md' are fed -into the hash function and the results are kept in the global 'md'. - -I believe the above addressed points 1 (use of SHA-1), 6 (by hashing -into the 'state' the 'old' data from the caller that is about to be -overwritten) and 7 (by not using the 10 bytes given to the caller to -update the 'state', but they are used to update 'md'). - -So of the points raised, only 2 is not addressed (but see -L<RAND_add(3)|RAND_add(3)>). - -=head1 SEE ALSO - -L<BN_rand(3)|BN_rand(3)>, L<RAND_add(3)|RAND_add(3)>, -L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_egd(3)|RAND_egd(3)>, -L<RAND_bytes(3)|RAND_bytes(3)>, -L<RAND_set_rand_method(3)|RAND_set_rand_method(3)>, -L<RAND_cleanup(3)|RAND_cleanup(3)> - -=cut diff --git a/openssl/doc/crypto/rc4.pod b/openssl/doc/crypto/rc4.pod deleted file mode 100644 index b6d3a43..0000000 --- a/openssl/doc/crypto/rc4.pod +++ /dev/null @@ -1,62 +0,0 @@ -=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. - -Applications should use the higher level functions -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> -etc. instead of calling the RC4 functions directly. - -=head1 RETURN VALUES - -RC4_set_key() and RC4() do not return values. - -=head1 NOTE - -Certain conditions have to be observed to securely use stream ciphers. -It is not permissible to perform multiple encryptions using the same -key stream. - -=head1 SEE ALSO - -L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)> - -=head1 HISTORY - -RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/ripemd.pod b/openssl/doc/crypto/ripemd.pod deleted file mode 100644 index 264bb99..0000000 --- a/openssl/doc/crypto/ripemd.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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>. - -Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the -hash functions directly. - -=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 CONFORMING TO - -ISO/IEC 10118-3 (draft) (??) - -=head1 SEE ALSO - -L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and -RIPEMD160_Final() are available since SSLeay 0.9.0. - -=cut diff --git a/openssl/doc/crypto/rsa.pod b/openssl/doc/crypto/rsa.pod deleted file mode 100644 index 45ac53f..0000000 --- a/openssl/doc/crypto/rsa.pod +++ /dev/null @@ -1,123 +0,0 @@ -=pod - -=head1 NAME - -rsa - RSA public key cryptosystem - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - #include <openssl/engine.h> - - RSA * RSA_new(void); - void RSA_free(RSA *rsa); - - int RSA_public_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - int RSA_private_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - int RSA_private_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa,int padding); - int RSA_public_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa,int padding); - - int RSA_sign(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - int RSA_verify(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - - int RSA_size(const RSA *rsa); - - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); - - int RSA_check_key(RSA *rsa); - - int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); - void RSA_blinding_off(RSA *rsa); - - void RSA_set_default_method(const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_default_method(void); - int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_method(const RSA *rsa); - RSA_METHOD *RSA_PKCS1_SSLeay(void); - RSA_METHOD *RSA_null_method(void); - int RSA_flags(const RSA *rsa); - RSA *RSA_new_method(ENGINE *engine); - - int RSA_print(BIO *bp, RSA *x, int offset); - int RSA_print_fp(FILE *fp, RSA *x, int offset); - - int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int RSA_set_ex_data(RSA *r,int idx,char *arg); - char *RSA_get_ex_data(RSA *r, int idx); - - 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 - -These functions implement RSA public key encryption and signatures -as defined in PKCS #1 v2.0 [RFC 2437]. - -The B<RSA> structure consists of several BIGNUM components. It can -contain public as well as private RSA keys: - - struct - { - BIGNUM *n; // public modulus - BIGNUM *e; // public exponent - BIGNUM *d; // private exponent - BIGNUM *p; // secret prime factor - BIGNUM *q; // secret prime factor - BIGNUM *dmp1; // d mod (p-1) - BIGNUM *dmq1; // d mod (q-1) - BIGNUM *iqmp; // q^-1 mod p - // ... - }; - RSA - -In public keys, the private exponent and the related secret values are -B<NULL>. - -B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private -keys, but the RSA operations are much faster when these values are -available. - -Note that RSA keys may use non-standard B<RSA_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using RSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 PATENTS - -RSA was covered by a US patent which expired in September 2000. - -=head1 SEE ALSO - -L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, -L<rand(3)|rand(3)>, L<engine(3)|engine(3)>, L<RSA_new(3)|RSA_new(3)>, -L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>, -L<RSA_generate_key(3)|RSA_generate_key(3)>, -L<RSA_check_key(3)|RSA_check_key(3)>, -L<RSA_blinding_on(3)|RSA_blinding_on(3)>, -L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>, -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, -L<RSA_sign_ASN1_OCTET_STRING(3)|RSA_sign_ASN1_OCTET_STRING(3)>, -L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)> - -=cut diff --git a/openssl/doc/crypto/sha.pod b/openssl/doc/crypto/sha.pod deleted file mode 100644 index 0c9dbf2..0000000 --- a/openssl/doc/crypto/sha.pod +++ /dev/null @@ -1,104 +0,0 @@ -=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)|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<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all -versions of SSLeay and OpenSSL. - -=cut diff --git a/openssl/doc/crypto/threads.pod b/openssl/doc/crypto/threads.pod deleted file mode 100644 index dc0e939..0000000 --- a/openssl/doc/crypto/threads.pod +++ /dev/null @@ -1,210 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, -CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, -CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, -CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, -CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, -CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support - -=head1 SYNOPSIS - - #include <openssl/crypto.h> - - /* Don't use this structure directly. */ - typedef struct crypto_threadid_st - { - void *ptr; - unsigned long val; - } CRYPTO_THREADID; - /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ - void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); - void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); - int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); - void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); - void CRYPTO_THREADID_current(CRYPTO_THREADID *id); - int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, - const CRYPTO_THREADID *b); - void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, - const CRYPTO_THREADID *src); - unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); - - int CRYPTO_num_locks(void); - - /* struct CRYPTO_dynlock_value needs to be defined by the user */ - struct CRYPTO_dynlock_value; - - void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * - (*dyn_create_function)(char *file, int line)); - void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) - (int mode, struct CRYPTO_dynlock_value *l, - const char *file, int line)); - void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) - (struct CRYPTO_dynlock_value *l, const char *file, int line)); - - int CRYPTO_get_new_dynlockid(void); - - void CRYPTO_destroy_dynlockid(int i); - - void CRYPTO_lock(int mode, int n, const char *file, int line); - - #define CRYPTO_w_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_w_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_r_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_r_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_add(addr,amount,type) \ - CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) - -=head1 DESCRIPTION - -OpenSSL can safely be used in multi-threaded applications provided -that at least two callback functions are set, locking_function and -threadid_func. - -locking_function(int mode, int n, const char *file, int line) is -needed to perform locking on shared data structures. -(Note that OpenSSL uses a number of global data structures that -will be implicitly shared whenever multiple threads use OpenSSL.) -Multi-threaded applications will crash at random if it is not set. - -locking_function() must be able to handle up to CRYPTO_num_locks() -different mutex locks. It sets the B<n>-th lock if B<mode> & -B<CRYPTO_LOCK>, and releases it otherwise. - -B<file> and B<line> are the file number of the function setting the -lock. They can be useful for debugging. - -threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing -thread's identifier into B<id>. The implementation of this callback should not -fill in B<id> directly, but should use CRYPTO_THREADID_set_numeric() if thread -IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based. -If the application does not register such a callback using -CRYPTO_THREADID_set_callback(), then a default implementation is used - on -Windows and BeOS this uses the system's default thread identifying APIs, and on -all other platforms it uses the address of B<errno>. The latter is satisfactory -for thread-safety if and only if the platform has a thread-local error number -facility. - -Once threadid_func() is registered, or if the built-in default implementation is -to be used; - -=over 4 - -=item * -CRYPTO_THREADID_current() records the currently-executing thread ID into the -given B<id> object. - -=item * -CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie. -the same semantics as memcmp()). - -=item * -CRYPTO_THREADID_cpy() duplicates a thread ID value, - -=item * -CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This -is usually the exact numeric or pointer-based thread ID used internally, however -this also handles the unusual case where pointers are larger than 'long' -variables and the platform's thread IDs are pointer-based - in this case, mixing -is done to attempt to produce a unique numeric value even though it is not as -wide as the platform's true thread IDs. - -=back - -Additionally, OpenSSL supports dynamic locks, and sometimes, some parts -of OpenSSL need it for better performance. To enable this, the following -is required: - -=over 4 - -=item * -Three additional callback function, dyn_create_function, dyn_lock_function -and dyn_destroy_function. - -=item * -A structure defined with the data that each lock needs to handle. - -=back - -struct CRYPTO_dynlock_value has to be defined to contain whatever structure -is needed to handle locks. - -dyn_create_function(const char *file, int line) is needed to create a -lock. Multi-threaded applications might crash at random if it is not set. - -dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) -is needed to perform locking off dynamic lock numbered n. Multi-threaded -applications might crash at random if it is not set. - -dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is -needed to destroy the lock l. Multi-threaded applications might crash at -random if it is not set. - -CRYPTO_get_new_dynlockid() is used to create locks. It will call -dyn_create_function for the actual creation. - -CRYPTO_destroy_dynlockid() is used to destroy locks. It will call -dyn_destroy_function for the actual destruction. - -CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield -describing what should be done with the lock. n is the number of the -lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined -from the following values. These values are pairwise exclusive, with -undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE -should not be used together): - - CRYPTO_LOCK 0x01 - CRYPTO_UNLOCK 0x02 - CRYPTO_READ 0x04 - CRYPTO_WRITE 0x08 - -=head1 RETURN VALUES - -CRYPTO_num_locks() returns the required number of locks. - -CRYPTO_get_new_dynlockid() returns the index to the newly created lock. - -The other functions return no values. - -=head1 NOTES - -You can find out if OpenSSL was configured with thread support: - - #define OPENSSL_THREAD_DEFINES - #include <openssl/opensslconf.h> - #if defined(OPENSSL_THREADS) - // thread support enabled - #else - // no thread support - #endif - -Also, dynamic locks are currently not used internally by OpenSSL, but -may do so in the future. - -=head1 EXAMPLES - -B<crypto/threads/mttest.c> shows examples of the callback functions on -Solaris, Irix and Win32. - -=head1 HISTORY - -CRYPTO_set_locking_callback() is -available in all versions of SSLeay and OpenSSL. -CRYPTO_num_locks() was added in OpenSSL 0.9.4. -All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. -B<CRYPTO_THREADID> and associated functions were introduced in OpenSSL 1.0.0 -to replace (actually, deprecate) the previous CRYPTO_set_id_callback(), -CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed -thread IDs to always be represented by 'unsigned long'. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)> - -=cut diff --git a/openssl/doc/crypto/ui.pod b/openssl/doc/crypto/ui.pod deleted file mode 100644 index 2e94d8c..0000000 --- a/openssl/doc/crypto/ui.pod +++ /dev/null @@ -1,194 +0,0 @@ -=pod - -=head1 NAME - -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, ERR_load_UI_strings - New User Interface - -=head1 SYNOPSIS - - #include <openssl/ui.h> - - typedef struct ui_st UI; - typedef struct ui_method_st UI_METHOD; - - 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); - - /* These are the possible flags. They can be or'ed together. */ - #define UI_INPUT_FLAG_ECHO 0x01 - #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 - - 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)()); - #define UI_CTRL_PRINT_ERRORS 1 - #define UI_CTRL_IS_REDOABLE 2 - - 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); - -=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(3)|ui_create(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 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_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. - -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 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 -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. - -UI_ctrl() adds extra control for the application author. For now, it -understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process() -print the OpenSSL error stack as part of processing the UI, and -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. - -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 SEE ALSO - -L<ui_create(3)|ui_create(3)>, L<ui_compat(3)|ui_compat(3)> - -=head1 HISTORY - -The UI section was first introduced in OpenSSL 0.9.7. - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/openssl/doc/crypto/ui_compat.pod b/openssl/doc/crypto/ui_compat.pod deleted file mode 100644 index adf2ae5..0000000 --- a/openssl/doc/crypto/ui_compat.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw - -Compatibility user interface functions - -=head1 SYNOPSIS - - #include <openssl/des_old.h> - - int des_read_password(DES_cblock *key,const char *prompt,int verify); - int des_read_2passwords(DES_cblock *key1,DES_cblock *key2, - const char *prompt,int verify); - - int des_read_pw_string(char *buf,int length,const char *prompt,int verify); - int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify); - -=head1 DESCRIPTION - -The DES library contained a few routines to prompt for passwords. These -aren't necessarely dependent on DES, and have therefore become part of the -UI compatibility library. - -des_read_pw() writes the string specified by I<prompt> to standard output -turns echo off and reads an input string from the terminal. The string is -returned in I<buf>, which must have spac for at least I<size> bytes. -If I<verify> is set, the user is asked for the password twice and unless -the two copies match, an error is returned. The second password is stored -in I<buff>, which must therefore also be at least I<size> bytes. A return -code of -1 indicates a system error, 1 failure due to use interaction, and -0 is success. All other functions described here use des_read_pw() to do -the work. - -des_read_pw_string() is a variant of des_read_pw() that provides a buffer -for you if I<verify> is set. - -des_read_password() calls des_read_pw() and converts the password to a -DES key by calling DES_string_to_key(); des_read_2password() operates in -the same way as des_read_password() except that it generates two keys -by using the DES_string_to_2key() function. - -=head1 NOTES - -des_read_pw_string() is available in the MIT Kerberos library as well, and -is also available under the name EVP_read_pw_string(). - -=head1 SEE ALSO - -L<ui(3)|ui(3)>, L<ui_create(3)|ui_create(3)> - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/openssl/doc/crypto/x509.pod b/openssl/doc/crypto/x509.pod deleted file mode 100644 index f9e58e0..0000000 --- a/openssl/doc/crypto/x509.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -x509 - X.509 certificate handling - -=head1 SYNOPSIS - - #include <openssl/x509.h> - -=head1 DESCRIPTION - -A 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)|X509_NAME_ENTRY_get_object(3)>, -L<X509_NAME_add_entry_by_txt(3)|X509_NAME_add_entry_by_txt(3)>, -L<X509_NAME_add_entry_by_NID(3)|X509_NAME_add_entry_by_NID(3)>, -L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>, -L<X509_NAME_new(3)|X509_NAME_new(3)>, -L<d2i_X509(3)|d2i_X509(3)>, -L<d2i_X509_ALGOR(3)|d2i_X509_ALGOR(3)>, -L<d2i_X509_CRL(3)|d2i_X509_CRL(3)>, -L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, -L<d2i_X509_REQ(3)|d2i_X509_REQ(3)>, -L<d2i_X509_SIG(3)|d2i_X509_SIG(3)>, -L<crypto(3)|crypto(3)>, -L<x509v3(3)|x509v3(3)> - -=cut diff --git a/openssl/doc/dir-locals.example.el b/openssl/doc/dir-locals.example.el deleted file mode 100644 index 79d0b01..0000000 --- a/openssl/doc/dir-locals.example.el +++ /dev/null @@ -1,15 +0,0 @@ -;;; 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 . 78) - ) - (c-mode - (c-file-style . "OpenSSL-II"))) diff --git a/openssl/doc/fingerprints.txt b/openssl/doc/fingerprints.txt deleted file mode 100644 index 373e90d..0000000 --- a/openssl/doc/fingerprints.txt +++ /dev/null @@ -1,63 +0,0 @@ - Fingerprints - -OpenSSL releases are signed with PGP/GnuPG keys. You can find the -signatures in separate files in the same location you find the -distributions themselves. The normal file name is the same as the -distribution file, with '.asc' added. For example, the signature for -the distribution of OpenSSL 1.0.1h, openssl-1.0.1h.tar.gz, is found in -the file openssl-1.0.1h.tar.gz.asc. - -The following is the list of fingerprints for the keys that are -currently in use to sign OpenSSL distributions: - -pub 1024D/F709453B 2003-10-20 - Key fingerprint = C4CA B749 C34F 7F4C C04F DAC9 A7AF 9E78 F709 453B -uid Richard Levitte <richard@levitte.org> -uid Richard Levitte <levitte@openssl.org> -uid Richard Levitte <levitte@lp.se> - -pub 2048R/F295C759 1998-12-13 - Key fingerprint = D0 5D 8C 61 6E 27 E6 60 41 EC B1 B8 D5 7E E5 97 -uid Dr S N Henson <shenson@drh-consultancy.demon.co.uk> - -pub 4096R/FA40E9E2 2005-03-19 - Key fingerprint = 6260 5AA4 334A F9F0 DDE5 D349 D357 7507 FA40 E9E2 -uid Dr Stephen Henson <shenson@opensslfoundation.com> -uid Dr Stephen Henson <shenson@drh-consultancy.co.uk> -uid Dr Stephen N Henson <steve@openssl.org> -sub 4096R/8811F530 2005-03-19 - -pub 1024R/49A563D9 1997-02-24 - Key fingerprint = 7B 79 19 FA 71 6B 87 25 0E 77 21 E5 52 D9 83 BF -uid Mark Cox <mjc@redhat.com> -uid Mark Cox <mark@awe.com> -uid Mark Cox <mjc@apache.org> - -pub 1024R/9C58A66D 1997-04-03 - Key fingerprint = 13 D0 B8 9D 37 30 C3 ED AC 9C 24 7D 45 8C 17 67 -uid jaenicke@openssl.org -uid Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE> - -pub 1024D/2118CF83 1998-07-13 - Key fingerprint = 7656 55DE 62E3 96FF 2587 EB6C 4F6D E156 2118 CF83 -uid Ben Laurie <ben@thebunker.net> -uid Ben Laurie <ben@cryptix.org> -uid Ben Laurie <ben@algroup.co.uk> -sub 4096g/1F5143E7 1998-07-13 - -pub 1024R/5A6A9B85 1994-03-22 - Key fingerprint = C7 AC 7E AD 56 6A 65 EC F6 16 66 83 7E 86 68 28 -uid Bodo Moeller <2005@bmoeller.de> -uid Bodo Moeller <2003@bmoeller.de> -uid Bodo Moeller <2004@bmoeller.de> -uid Bodo Moeller <bmoeller@acm.org> -uid Bodo Moeller <bodo@openssl.org> -uid Bodo Moeller <bm@ulf.mali.sub.org> -uid Bodo Moeller <3moeller@informatik.uni-hamburg.de> -uid Bodo Moeller <Bodo_Moeller@public.uni-hamburg.de> -uid Bodo Moeller <3moeller@rzdspc5.informatik.uni-hamburg.de> - -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/doc/openssl-c-indent.el b/openssl/doc/openssl-c-indent.el deleted file mode 100644 index 144a915..0000000 --- a/openssl/doc/openssl-c-indent.el +++ /dev/null @@ -1,62 +0,0 @@ -;;; 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 releaes 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 a 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 explicitely 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/doc/openssl-shared.txt b/openssl/doc/openssl-shared.txt deleted file mode 100644 index 5cf84a0..0000000 --- a/openssl/doc/openssl-shared.txt +++ /dev/null @@ -1,32 +0,0 @@ -The OpenSSL shared libraries are often installed in a directory like -/usr/local/ssl/lib. - -If this directory is not in a standard system path for dynamic/shared -libraries, then you will have problems linking and executing -applications that use OpenSSL libraries UNLESS: - -* you link with static (archive) libraries. If you are truly - paranoid about security, you should use static libraries. -* you use the GNU libtool code during linking - (http://www.gnu.org/software/libtool/libtool.html) -* you use pkg-config during linking (this requires that - PKG_CONFIG_PATH includes the path to the OpenSSL shared - library directory), and make use of -R or -rpath. - (http://www.freedesktop.org/software/pkgconfig/) -* you specify the system-wide link path via a command such - as crle(1) on Solaris systems. -* you add the OpenSSL shared library directory to /etc/ld.so.conf - and run ldconfig(8) on Linux systems. -* you define the LD_LIBRARY_PATH, LIBPATH, SHLIB_PATH (HP), - DYLD_LIBRARY_PATH (MacOS X) or PATH (Cygwin and DJGPP) - environment variable and add the OpenSSL shared library - directory to it. - -One common tool to check the dynamic dependencies of an executable -or dynamic library is ldd(1) on most UNIX systems. - -See any operating system documentation and manpages about shared -libraries for your version of UNIX. The following manpages may be -helpful: ld(1), ld.so(1), ld.so.1(1) [Solaris], dld.sl(1) [HP], -ldd(1), crle(1) [Solaris], pldd(1) [Solaris], ldconfig(8) [Linux], -chatr(1) [HP]. diff --git a/openssl/doc/openssl.txt b/openssl/doc/openssl.txt deleted file mode 100644 index f8817b0..0000000 --- a/openssl/doc/openssl.txt +++ /dev/null @@ -1,1254 +0,0 @@ - -This is some preliminary documentation for OpenSSL. - -Contents: - - OpenSSL X509V3 extension configuration - X509V3 Extension code: programmers guide - PKCS#12 Library - - -============================================================================== - OpenSSL X509V3 extension configuration -============================================================================== - -OpenSSL X509V3 extension configuration: preliminary documentation. - -INTRODUCTION. - -For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now -possible to add and print out common X509 V3 certificate and CRL extensions. - -BEGINNERS NOTE - -For most simple applications you don't need to know too much about extensions: -the default openssl.cnf values will usually do sensible things. - -If you want to know more you can initially quickly look through the sections -describing how the standard OpenSSL utilities display and add extensions and -then the list of supported extensions. - -For more technical information about the meaning of extensions see: - -http://www.imc.org/ietf-pkix/ -http://home.netscape.com/eng/security/certs.html - -PRINTING EXTENSIONS. - -Extension values are automatically printed out for supported extensions. - -openssl x509 -in cert.pem -text -openssl crl -in crl.pem -text - -will give information in the extension printout, for example: - - X509v3 extensions: - X509v3 Basic Constraints: - CA:TRUE - X509v3 Subject Key Identifier: - 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15 - X509v3 Authority Key Identifier: - keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00 - X509v3 Key Usage: - Certificate Sign, CRL Sign - X509v3 Subject Alternative Name: - email:email@1.address, email:email@2.address - -CONFIGURATION FILES. - -The OpenSSL utilities 'ca' and 'req' can now have extension sections listing -which certificate extensions to include. In each case a line: - -x509_extensions = extension_section - -indicates which section contains the extensions. In the case of 'req' the -extension section is used when the -x509 option is present to create a -self signed root certificate. - -The 'x509' utility also supports extensions when it signs a certificate. -The -extfile option is used to set the configuration file containing the -extensions. In this case a line with: - -extensions = extension_section - -in the nameless (default) section is used. If no such line is included then -it uses the default section. - -You can also add extensions to CRLs: a line - -crl_extensions = crl_extension_section - -will include extensions when the -gencrl option is used with the 'ca' utility. -You can add any extension to a CRL but of the supported extensions only -issuerAltName and authorityKeyIdentifier make any real sense. Note: these are -CRL extensions NOT CRL *entry* extensions which cannot currently be generated. -CRL entry extensions can be displayed. - -NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL -you should not include a crl_extensions line in the configuration file. - -As with all configuration files you can use the inbuilt environment expansion -to allow the values to be passed in the environment. Therefore if you have -several extension sections used for different purposes you can have a line: - -x509_extensions = $ENV::ENV_EXT - -and set the ENV_EXT environment variable before calling the relevant utility. - -EXTENSION SYNTAX. - -Extensions have the basic form: - -extension_name=[critical,] extension_options - -the use of the critical option makes the extension critical. Extreme caution -should be made when using the critical flag. If an extension is marked -as critical then any client that does not understand the extension should -reject it as invalid. Some broken software will reject certificates which -have *any* critical extensions (these violates PKIX but we have to live -with it). - -There are three main types of extension: string extensions, multi-valued -extensions, and raw 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. However it should be noted that in some cases the -same name can appear multiple times, for example, - -subjectAltName=email:steve@here,email:steve@there - -in this case an equivalent long form is: - -subjectAltName=@alt_section - -[alt_section] - -email.1=steve@here -email.2=steve@there - -This is because the configuration file code cannot handle the same name -occurring twice in the same section. - -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. - -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 ASN1_generate_nconf(). 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 arbitrary 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 - -WARNING: DER should be used with caution. It is possible to create totally -invalid extensions unless care is taken. - -CURRENTLY SUPPORTED EXTENSIONS. - -If you aren't sure about extensions then they can be largely ignored: its only -when you want to do things like restrict certificate usage when you need to -worry about them. - -The only extension that a beginner might want to look at is Basic Constraints. -If in addition you want to try Netscape object signing the you should also -look at Netscape Certificate Type. - -Literal String extensions. - -In each case the 'value' of the extension is placed directly in the -extension. Currently supported extensions in this category are: nsBaseUrl, -nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, -nsSslServerName and nsComment. - -For example: - -nsComment="This is a test comment" - -Bit Strings. - -Bit string extensions just consist of a list of supported bits, currently -two extensions are in this category: PKIX keyUsage and the Netscape specific -nsCertType. - -nsCertType (netscape certificate type) takes the flags: client, server, email, -objsign, reserved, sslCA, emailCA, objCA. - -keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation, -keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, -encipherOnly, decipherOnly. - -For example: - -nsCertType=server - -keyUsage=digitalSignature, nonRepudiation - -Hints on Netscape Certificate Type. - -Other than Basic Constraints this is the only extension a beginner might -want to use, if you want to try Netscape object signing, otherwise it can -be ignored. - -If you want a certificate that can be used just for object signing then: - -nsCertType=objsign - -will do the job. If you want to use it as a normal end user and server -certificate as well then - -nsCertType=objsign,email,server - -is more appropriate. You cannot use a self signed certificate for object -signing (well Netscape signtool can but it cheats!) so you need to create -a CA certificate and sign an end user certificate with it. - -Side note: If you want to conform to the Netscape specifications then you -should really also set: - -nsCertType=objCA - -in the *CA* certificate for just an object signing CA and - -nsCertType=objCA,emailCA,sslCA - -for everything. Current Netscape software doesn't enforce this so it can -be omitted. - -Basic Constraints. - -This is generally the only extension you need to worry about for simple -applications. If you want your certificate to be usable as a CA certificate -(in addition to an end user certificate) then you set this to: - -basicConstraints=CA:TRUE - -if you want to be certain the certificate cannot be used as a CA then do: - -basicConstraints=CA:FALSE - -The rest of this section describes more advanced usage. - -Basic constraints is a multi-valued extension that supports a CA and an -optional pathlen option. The CA option takes the values true and false and -pathlen takes an integer. Note if the CA option is false the pathlen option -should be omitted. - -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. This all -assumes that the software correctly interprets this extension of course. - -Examples: - -basicConstraints=CA:TRUE -basicConstraints=critical,CA:TRUE, pathlen:0 - -NOTE: for a CA to be considered valid it must have the CA option set to -TRUE. An end user certificate MUST NOT have the CA value set to true. -According to PKIX recommendations it should exclude the extension entirely, -however some software may require CA set to FALSE for end entity certificates. - -Extended Key Usage. - -This extensions consists of a list of usages. - -These can either be object short names of 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 -msCodeInd Microsoft Individual Code Signing (authenticode) -msCodeCom Microsoft Commercial Code Signing (authenticode) -msCTLSign Microsoft Trust List Signing -msSGC Microsoft Server Gated Crypto -msEFS Microsoft Encrypted File System -nsSGC Netscape Server Gated Crypto - -For example, under IE5 a CA can be used for any purpose: by including a list -of the above usages the CA can be restricted to only authorised uses. - -Note: software packages may place additional interpretations on certificate -use, in particular some usages may only work for selected CAs. Don't for example -expect just including msSGC or nsSGC will automatically mean that a certificate -can be used for SGC ("step up" encryption) otherwise anyone could use it. - -Examples: - -extendedKeyUsage=critical,codeSigning,1.2.3.4 -extendedKeyUsage=nsSGC,msSGC - -Subject Key Identifier. - -This is really a string extension and can take two possible values. Either -a hex string giving details of the extension value to include or the word -'hash' which then automatically follow PKIX guidelines in selecting and -appropriate key identifier. The use of the hex string is strongly discouraged. - -Example: subjectKeyIdentifier=hash - -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. Normally this will only be done if the keyid option fails or -is not included: the "always" flag will always include the value. - -Subject Alternative Name. - -The subject alternative name extension allows various literal values to be -included in the configuration file. These include "email" (an email address) -"URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a -registered ID: OBJECT IDENTIFIER), IP (and IP address) and otherName. - -Also the email option include a special 'copy' value. This will automatically -include and email addresses contained in the certificate subject name in -the extension. - -otherName can include arbitrary data associated with an OID: the value -should be the OID followed by a semicolon and the content in standard -ASN1_generate_nconf() format. - -Examples: - -subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ -subjectAltName=email:my@other.address,RID:1.2.3.4 -subjectAltName=otherName:1.2.3.4;UTF8:some other identifier - -Issuer Alternative Name. - -The issuer alternative name option supports all the literal options of -subject alternative name. It does *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 - -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 '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. OCSP gives the -location of an OCSP responder: this is used by Netscape PSM and other software. - -Example: - -authorityInfoAccess = OCSP;URI:http://ocsp.my.host/ -authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html - -CRL distribution points. - -This is a multi-valued extension that supports all the literal options of -subject alternative name. Of the few software packages that currently interpret -this extension most only interpret the URI option. - -Currently each option will set a new DistributionPoint with the fullName -field set to the given value. - -Other fields like cRLissuer and reasons cannot currently be set or displayed: -at this time no examples were available that used these fields. - -If you see this extension with <UNSUPPORTED> when you attempt to print it out -or it doesn't appear to display correctly then let me know, including the -certificate (mail me at steve@openssl.org) . - -Examples: - -crlDistributionPoints=URI:http://www.myhost.com/myca.crl -crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl - -Certificate Policies. - -This is a RAW extension. It attempts to display the contents of this extension: -unfortunately this extension is often improperly encoded. - -The certificate policies extension will rarely be used in practice: few -software packages interpret it correctly or at all. IE5 does partially -support this extension: but it needs the 'ia5org' option because it will -only correctly support a broken encoding. Of the options below only the -policy OID, explicitText and CPS options are displayed with IE5. - -All the fields of this extension can be set by using the appropriate syntax. - -If you follow the PKIX recommendations of not including any qualifiers and just -using only 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 - -TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field, -according to PKIX it should be of type DisplayText but Verisign uses an -IA5STRING and IE5 needs this too. - -Display only extensions. - -Some extensions are only partially supported and currently are only displayed -but cannot be set. These include private key usage period, CRL number, and -CRL reason. - -============================================================================== - X509V3 Extension code: programmers guide -============================================================================== - -The purpose of the extension code is twofold. It allows an extension to be -created from a string or structure describing its contents and it prints out an -extension in a human or machine readable form. - -1. Initialisation and cleanup. - -No special initialisation is needed before calling the extension functions. -You used to have to call X509V3_add_standard_extensions(); but this is no longer -required and this function no longer does anything. - -void X509V3_EXT_cleanup(void); - -This function should be called to cleanup the extension code if any custom -extensions have been added. If no custom extensions have been added then this -call does nothing. After this call all custom extension code is freed up but -you can still use the standard extensions. - -2. Printing and parsing extensions. - -The simplest way to print out extensions is via the standard X509 printing -routines: if you use the standard X509_print() function, the supported -extensions will be printed out automatically. - -The following functions allow finer control over extension display: - -int X509V3_EXT_print(BIO *out, X509_EXTENSION *ext, int flag, int indent); -int X509V3_EXT_print_fp(FILE *out, X509_EXTENSION *ext, int flag, int indent); - -These two functions print out an individual extension to a BIO or FILE pointer. -Currently the flag argument is unused and should be set to 0. The 'indent' -argument is the number of spaces to indent each line. - -void *X509V3_EXT_d2i(X509_EXTENSION *ext); - -This function parses an extension and returns its internal structure. The -precise structure you get back depends on the extension being parsed. If the -extension if basicConstraints you will get back a pointer to a -BASIC_CONSTRAINTS structure. Check out the source in crypto/x509v3 for more -details about the structures returned. The returned structure should be freed -after use using the relevant free function, BASIC_CONSTRAINTS_free() for -example. - -void * X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx); -void * X509_CRL_get_ext_d2i(X509_CRL *x, int nid, int *crit, int *idx); -void * X509_REVOKED_get_ext_d2i(X509_REVOKED *x, int nid, int *crit, int *idx); -void * X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit, int *idx); - -These functions combine the operations of searching for extensions and -parsing them. They search a certificate, a CRL a CRL entry or a stack -of extensions respectively for extension whose NID is 'nid' and return -the parsed result of NULL if an error occurred. For example: - -BASIC_CONSTRAINTS *bs; -bs = X509_get_ext_d2i(cert, NID_basic_constraints, NULL, NULL); - -This will search for the basicConstraints extension and either return -it value or NULL. NULL can mean either the extension was not found, it -occurred more than once or it could not be parsed. - -If 'idx' is NULL then an extension is only parsed if it occurs precisely -once. This is standard behaviour because extensions normally cannot occur -more than once. If however more than one extension of the same type can -occur it can be used to parse successive extensions for example: - -int i; -void *ext; - -i = -1; -for(;;) { - ext = X509_get_ext_d2i(x, nid, crit, &idx); - if(ext == NULL) break; - /* Do something with ext */ -} - -If 'crit' is not NULL and the extension was found then the int it points to -is set to 1 for critical extensions and 0 for non critical. Therefore if the -function returns NULL but 'crit' is set to 0 or 1 then the extension was -found but it could not be parsed. - -The int pointed to by crit will be set to -1 if the extension was not found -and -2 if the extension occurred more than once (this will only happen if -idx is NULL). In both cases the function will return NULL. - -3. Generating extensions. - -An extension will typically be generated from a configuration file, or some -other kind of configuration database. - -int X509V3_EXT_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, - X509 *cert); -int X509V3_EXT_CRL_add_conf(LHASH *conf, X509V3_CTX *ctx, char *section, - X509_CRL *crl); - -These functions add all the extensions in the given section to the given -certificate or CRL. They will normally be called just before the certificate -or CRL is due to be signed. Both return 0 on error on non zero for success. - -In each case 'conf' is the LHASH pointer of the configuration file to use -and 'section' is the section containing the extension details. - -See the 'context functions' section for a description of the ctx parameter. - - -X509_EXTENSION *X509V3_EXT_conf(LHASH *conf, X509V3_CTX *ctx, char *name, - char *value); - -This function returns an extension based on a name and value pair, if the -pair will not need to access other sections in a config file (or there is no -config file) then the 'conf' parameter can be set to NULL. - -X509_EXTENSION *X509V3_EXT_conf_nid(char *conf, X509V3_CTX *ctx, int nid, - char *value); - -This function creates an extension in the same way as X509V3_EXT_conf() but -takes the NID of the extension rather than its name. - -For example to produce basicConstraints with the CA flag and a path length of -10: - -x = X509V3_EXT_conf_nid(NULL, NULL, NID_basic_constraints,"CA:TRUE,pathlen:10"); - - -X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext_struc); - -This function sets up an extension from its internal structure. The ext_nid -parameter is the NID of the extension and 'crit' is the critical flag. - -4. Context functions. - -The following functions set and manipulate an extension context structure. -The purpose of the extension context is to allow the extension code to -access various structures relating to the "environment" of the certificate: -for example the issuers certificate or the certificate request. - -void X509V3_set_ctx(X509V3_CTX *ctx, X509 *issuer, X509 *subject, - X509_REQ *req, X509_CRL *crl, int flags); - -This function sets up an X509V3_CTX structure with details of the certificate -environment: specifically the issuers certificate, the subject certificate, -the certificate request and the CRL: if these are not relevant or not -available then they can be set to NULL. The 'flags' parameter should be set -to zero. - -X509V3_set_ctx_test(ctx) - -This macro is used to set the 'ctx' structure to a 'test' value: this is to -allow the syntax of an extension (or configuration file) to be tested. - -X509V3_set_ctx_nodb(ctx) - -This macro is used when no configuration database is present. - -void X509V3_set_conf_lhash(X509V3_CTX *ctx, LHASH *lhash); - -This function is used to set the configuration database when it is an LHASH -structure: typically a configuration file. - -The following functions are used to access a configuration database: they -should only be used in RAW extensions. - -char * X509V3_get_string(X509V3_CTX *ctx, char *name, char *section); - -This function returns the value of the parameter "name" in "section", or NULL -if there has been an error. - -void X509V3_string_free(X509V3_CTX *ctx, char *str); - -This function frees up the string returned by the above function. - -STACK_OF(CONF_VALUE) * X509V3_get_section(X509V3_CTX *ctx, char *section); - -This function returns a whole section as a STACK_OF(CONF_VALUE) . - -void X509V3_section_free( X509V3_CTX *ctx, STACK_OF(CONF_VALUE) *section); - -This function frees up the STACK returned by the above function. - -Note: it is possible to use the extension code with a custom configuration -database. To do this the "db_meth" element of the X509V3_CTX structure should -be set to an X509V3_CTX_METHOD structure. This structure contains the following -function pointers: - -char * (*get_string)(void *db, char *section, char *value); -STACK_OF(CONF_VALUE) * (*get_section)(void *db, char *section); -void (*free_string)(void *db, char * string); -void (*free_section)(void *db, STACK_OF(CONF_VALUE) *section); - -these will be called and passed the 'db' element in the X509V3_CTX structure -to access the database. If a given function is not implemented or not required -it can be set to NULL. - -5. String helper functions. - -There are several "i2s" and "s2i" functions that convert structures to and -from ASCII strings. In all the "i2s" cases the returned string should be -freed using Free() after use. Since some of these are part of other extension -code they may take a 'method' parameter. Unless otherwise stated it can be -safely set to NULL. - -char *i2s_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, ASN1_OCTET_STRING *oct); - -This returns a hex string from an ASN1_OCTET_STRING. - -char * i2s_ASN1_INTEGER(X509V3_EXT_METHOD *meth, ASN1_INTEGER *aint); -char * i2s_ASN1_ENUMERATED(X509V3_EXT_METHOD *meth, ASN1_ENUMERATED *aint); - -These return a string decimal representations of an ASN1_INTEGER and an -ASN1_ENUMERATED type, respectively. - -ASN1_OCTET_STRING *s2i_ASN1_OCTET_STRING(X509V3_EXT_METHOD *method, - X509V3_CTX *ctx, char *str); - -This converts an ASCII hex string to an ASN1_OCTET_STRING. - -ASN1_INTEGER * s2i_ASN1_INTEGER(X509V3_EXT_METHOD *meth, char *value); - -This converts a decimal ASCII string into an ASN1_INTEGER. - -6. Multi valued extension helper functions. - -The following functions can be used to manipulate STACKs of CONF_VALUE -structures, as used by multi valued extensions. - -int X509V3_get_value_bool(CONF_VALUE *value, int *asn1_bool); - -This function expects a boolean value in 'value' and sets 'asn1_bool' to -it. That is it sets it to 0 for FALSE or 0xff for TRUE. The following -strings are acceptable: "TRUE", "true", "Y", "y", "YES", "yes", "FALSE" -"false", "N", "n", "NO" or "no". - -int X509V3_get_value_int(CONF_VALUE *value, ASN1_INTEGER **aint); - -This accepts a decimal integer of arbitrary length and sets an ASN1_INTEGER. - -int X509V3_add_value(const char *name, const char *value, - STACK_OF(CONF_VALUE) **extlist); - -This simply adds a string name and value pair. - -int X509V3_add_value_uchar(const char *name, const unsigned char *value, - STACK_OF(CONF_VALUE) **extlist); - -The same as above but for an unsigned character value. - -int X509V3_add_value_bool(const char *name, int asn1_bool, - STACK_OF(CONF_VALUE) **extlist); - -This adds either "TRUE" or "FALSE" depending on the value of 'asn1_bool' - -int X509V3_add_value_bool_nf(char *name, int asn1_bool, - STACK_OF(CONF_VALUE) **extlist); - -This is the same as above except it adds nothing if asn1_bool is FALSE. - -int X509V3_add_value_int(const char *name, ASN1_INTEGER *aint, - STACK_OF(CONF_VALUE) **extlist); - -This function adds the value of the ASN1_INTEGER in decimal form. - -7. Other helper functions. - -<to be added> - -ADDING CUSTOM EXTENSIONS. - -Currently there are three types of supported extensions. - -String extensions are simple strings where the value is placed directly in the -extensions, and the string returned is printed out. - -Multi value extensions are passed a STACK_OF(CONF_VALUE) name and value pairs -or return a STACK_OF(CONF_VALUE). - -Raw extensions are just passed a BIO or a value and it is the extensions -responsibility to handle all the necessary printing. - -There are two ways to add an extension. One is simply as an alias to an already -existing extension. An alias is an extension that is identical in ASN1 structure -to an existing extension but has a different OBJECT IDENTIFIER. This can be -done by calling: - -int X509V3_EXT_add_alias(int nid_to, int nid_from); - -'nid_to' is the new extension NID and 'nid_from' is the already existing -extension NID. - -Alternatively an extension can be written from scratch. This involves writing -the ASN1 code to encode and decode the extension and functions to print out and -generate the extension from strings. The relevant functions are then placed in -a X509V3_EXT_METHOD structure and int X509V3_EXT_add(X509V3_EXT_METHOD *ext); -called. - -The X509V3_EXT_METHOD structure is described below. - -struct { -int ext_nid; -int ext_flags; -X509V3_EXT_NEW ext_new; -X509V3_EXT_FREE ext_free; -X509V3_EXT_D2I d2i; -X509V3_EXT_I2D i2d; -X509V3_EXT_I2S i2s; -X509V3_EXT_S2I s2i; -X509V3_EXT_I2V i2v; -X509V3_EXT_V2I v2i; -X509V3_EXT_R2I r2i; -X509V3_EXT_I2R i2r; - -void *usr_data; -}; - -The elements have the following meanings. - -ext_nid is the NID of the object identifier of the extension. - -ext_flags is set of flags. Currently the only external flag is - X509V3_EXT_MULTILINE which means a multi valued extensions - should be printed on separate lines. - -usr_data is an extension specific pointer to any relevant data. This - allows extensions to share identical code but have different - uses. An example of this is the bit string extension which uses - usr_data to contain a list of the bit names. - -All the remaining elements are function pointers. - -ext_new is a pointer to a function that allocates memory for the - extension ASN1 structure: for example ASN1_OBJECT_new(). - -ext_free is a pointer to a function that free up memory of the extension - ASN1 structure: for example ASN1_OBJECT_free(). - -d2i is the standard ASN1 function that converts a DER buffer into - the internal ASN1 structure: for example d2i_ASN1_IA5STRING(). - -i2d is the standard ASN1 function that converts the internal - structure into the DER representation: for example - i2d_ASN1_IA5STRING(). - -The remaining functions are depend on the type of extension. One i2X and -one X2i should be set and the rest set to NULL. The types set do not need -to match up, for example the extension could be set using the multi valued -v2i function and printed out using the raw i2r. - -All functions have the X509V3_EXT_METHOD passed to them in the 'method' -parameter and an X509V3_CTX structure. Extension code can then access the -parent structure via the 'method' parameter to for example make use of the value -of usr_data. If the code needs to use detail relating to the request it can -use the 'ctx' parameter. - -A note should be given here about the 'flags' member of the 'ctx' parameter. -If it has the value CTX_TEST then the configuration syntax is being checked -and no actual certificate or CRL exists. Therefore any attempt in the config -file to access such information should silently succeed. If the syntax is OK -then it should simply return a (possibly bogus) extension, otherwise it -should return NULL. - -char *i2s(struct v3_ext_method *method, void *ext); - -This function takes the internal structure in the ext parameter and returns -a Malloc'ed string representing its value. - -void * s2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); - -This function takes the string representation in the ext parameter and returns -an allocated internal structure: ext_free() will be used on this internal -structure after use. - -i2v and v2i handle a STACK_OF(CONF_VALUE): - -typedef struct -{ - char *section; - char *name; - char *value; -} CONF_VALUE; - -Only the name and value members are currently used. - -STACK_OF(CONF_VALUE) * i2v(struct v3_ext_method *method, void *ext); - -This function is passed the internal structure in the ext parameter and -returns a STACK of CONF_VALUE structures. The values of name, value, -section and the structure itself will be freed up with Free after use. -Several helper functions are available to add values to this STACK. - -void * v2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, - STACK_OF(CONF_VALUE) *values); - -This function takes a STACK_OF(CONF_VALUE) structures and should set the -values of the external structure. This typically uses the name element to -determine which structure element to set and the value element to determine -what to set it to. Several helper functions are available for this -purpose (see above). - -int i2r(struct v3_ext_method *method, void *ext, BIO *out, int indent); - -This function is passed the internal extension structure in the ext parameter -and sends out a human readable version of the extension to out. The 'indent' -parameter should be noted to determine the necessary amount of indentation -needed on the output. - -void * r2i(struct v3_ext_method *method, struct v3_ext_ctx *ctx, char *str); - -This is just passed the string representation of the extension. It is intended -to be used for more elaborate extensions where the standard single and multi -valued options are insufficient. They can use the 'ctx' parameter to parse the -configuration database themselves. See the context functions section for details -of how to do this. - -Note: although this type takes the same parameters as the "r2s" function there -is a subtle difference. Whereas an "r2i" function can access a configuration -database an "s2i" function MUST NOT. This is so the internal code can safely -assume that an "s2i" function will work without a configuration database. - -============================================================================== - PKCS#12 Library -============================================================================== - -This section describes the internal PKCS#12 support. There are very few -differences between the old external library and the new internal code at -present. This may well change because the external library will not be updated -much in future. - -This version now includes a couple of high level PKCS#12 functions which -generally "do the right thing" and should make it much easier to handle PKCS#12 -structures. - -HIGH LEVEL FUNCTIONS. - -For most applications you only need concern yourself with the high level -functions. They can parse and generate simple PKCS#12 files as produced by -Netscape and MSIE or indeed any compliant PKCS#12 file containing a single -private key and certificate pair. - -1. Initialisation and cleanup. - -No special initialisation is needed for the internal PKCS#12 library: the -standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to -add all algorithms (you should at least add SHA1 though) then you can manually -initialise the PKCS#12 library with: - -PKCS12_PBE_add(); - -The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is -called or it can be directly freed with: - -EVP_PBE_cleanup(); - -after this call (or EVP_cleanup() ) no more PKCS#12 library functions should -be called. - -2. I/O functions. - -i2d_PKCS12_bio(bp, p12) - -This writes out a PKCS12 structure to a BIO. - -i2d_PKCS12_fp(fp, p12) - -This is the same but for a FILE pointer. - -d2i_PKCS12_bio(bp, p12) - -This reads in a PKCS12 structure from a BIO. - -d2i_PKCS12_fp(fp, p12) - -This is the same but for a FILE pointer. - -3. High level functions. - -3.1 Parsing with PKCS12_parse(). - -int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert, - STACK **ca); - -This function takes a PKCS12 structure and a password (ASCII, null terminated) -and returns the private key, the corresponding certificate and any CA -certificates. If any of these is not required it can be passed as a NULL. -The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK -structure. Typically to read in a PKCS#12 file you might do: - -p12 = d2i_PKCS12_fp(fp, NULL); -PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */ -PKCS12_free(p12); - -3.2 PKCS#12 creation with PKCS12_create(). - -PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, - STACK *ca, int nid_key, int nid_cert, int iter, - int mac_iter, int keytype); - -This function will create a PKCS12 structure from a given password, name, -private key, certificate and optional STACK of CA certificates. The remaining -5 parameters can be set to 0 and sensible defaults will be used. - -The parameters nid_key and nid_cert are the key and certificate encryption -algorithms, iter is the encryption iteration count, mac_iter is the MAC -iteration count and keytype is the type of private key. If you really want -to know what these last 5 parameters do then read the low level section. - -Typically to create a PKCS#12 file the following could be used: - -p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0); -i2d_PKCS12_fp(fp, p12); -PKCS12_free(p12); - -3.3 Changing a PKCS#12 structure password. - -int PKCS12_newpass(PKCS12 *p12, char *oldpass, char *newpass); - -This changes the password of an already existing PKCS#12 structure. oldpass -is the old password and newpass is the new one. An error occurs if the old -password is incorrect. - -LOW LEVEL FUNCTIONS. - -In some cases the high level functions do not provide the necessary -functionality. For example if you want to generate or parse more complex -PKCS#12 files. The sample pkcs12 application uses the low level functions -to display details about the internal structure of a PKCS#12 file. - -Introduction. - -This is a brief description of how a PKCS#12 file is represented internally: -some knowledge of PKCS#12 is assumed. - -A PKCS#12 object contains several levels. - -At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a -CRL, a private key, encrypted or unencrypted, a set of safebags (so the -structure can be nested) or other secrets (not documented at present). -A safebag can optionally have attributes, currently these are: a unicode -friendlyName (a Unicode string) or a localKeyID (a string of bytes). - -At the next level is an authSafe which is a set of safebags collected into -a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself. - -At the top level is the PKCS12 structure itself which contains a set of -authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it -contains a MAC which is a kind of password protected digest to preserve -integrity (so any unencrypted stuff below can't be tampered with). - -The reason for these levels is so various objects can be encrypted in various -ways. For example you might want to encrypt a set of private keys with -triple-DES and then include the related certificates either unencrypted or -with lower encryption. Yes it's the dreaded crypto laws at work again which -allow strong encryption on private keys and only weak encryption on other -stuff. - -To build one of these things you turn all certificates and keys into safebags -(with optional attributes). You collect the safebags into (one or more) STACKS -and convert these into authsafes (encrypted or unencrypted). The authsafes -are collected into a STACK and added to a PKCS12 structure. Finally a MAC -inserted. - -Pulling one apart is basically the reverse process. The MAC is verified against -the given password. The authsafes are extracted and each authsafe split into -a set of safebags (possibly involving decryption). Finally the safebags are -decomposed into the original keys and certificates and the attributes used to -match up private key and certificate pairs. - -Anyway here are the functions that do the dirty work. - -1. Construction functions. - -1.1 Safebag functions. - -M_PKCS12_x5092certbag(x509) - -This macro takes an X509 structure and returns a certificate bag. The -X509 structure can be freed up after calling this function. - -M_PKCS12_x509crl2certbag(crl) - -As above but for a CRL. - -PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey) - -Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure. -Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo -structure contains a private key data in plain text form it should be free'd -up as soon as it has been encrypted for security reasons (freeing up the -structure zeros out the sensitive data). This can be done with -PKCS8_PRIV_KEY_INFO_free(). - -PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage) - -This sets the key type when a key is imported into MSIE or Outlook 98. Two -values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type -key that can also be used for signing but its size is limited in the export -versions of MS software to 512 bits, it is also the default. KEY_SIG is a -signing only key but the keysize is unlimited (well 16K is supposed to work). -If you are using the domestic version of MSIE then you can ignore this because -KEY_EX is not limited and can be used for both. - -PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8) - -Convert a PKCS8 private key structure into a keybag. This routine embeds the -p8 structure in the keybag so p8 should not be freed up or used after it is -called. The p8 structure will be freed up when the safebag is freed. - -PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8) - -Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not -embedded and can be freed up after use. - -int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) -int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen) - -Add a local key id or a friendlyname to a safebag. - -1.2 Authsafe functions. - -PKCS7 *PKCS12_pack_p7data(STACK *sk) -Take a stack of safebags and convert them into an unencrypted authsafe. The -stack of safebags can be freed up after calling this function. - -PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags); - -As above but encrypted. - -1.3 PKCS12 functions. - -PKCS12 *PKCS12_init(int mode) - -Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data). - -M_PKCS12_pack_authsafes(p12, safes) - -This macro takes a STACK of authsafes and adds them to a PKCS#12 structure. - -int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type); - -Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests -that SHA-1 should be used. - -2. Extraction Functions. - -2.1 Safebags. - -M_PKCS12_bag_type(bag) - -Return the type of "bag". Returns one of the following - -NID_keyBag -NID_pkcs8ShroudedKeyBag 7 -NID_certBag 8 -NID_crlBag 9 -NID_secretBag 10 -NID_safeContentsBag 11 - -M_PKCS12_cert_bag_type(bag) - -Returns type of certificate bag, following are understood. - -NID_x509Certificate 14 -NID_sdsiCertificate 15 - -M_PKCS12_crl_bag_type(bag) - -Returns crl bag type, currently only NID_crlBag is recognised. - -M_PKCS12_certbag2x509(bag) - -This macro extracts an X509 certificate from a certificate bag. - -M_PKCS12_certbag2x509crl(bag) - -As above but for a CRL. - -EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8) - -Extract a private key from a PKCS8 private key info structure. - -M_PKCS12_decrypt_skey(bag, pass, passlen) - -Decrypt a shrouded key bag and return a PKCS8 private key info structure. -Works with both RSA and DSA keys - -char *PKCS12_get_friendlyname(bag) - -Returns the friendlyName of a bag if present or NULL if none. The returned -string is a null terminated ASCII string allocated with Malloc(). It should -thus be freed up with Free() after use. - -2.2 AuthSafe functions. - -M_PKCS12_unpack_p7data(p7) - -Extract a STACK of safe bags from a PKCS#7 data ContentInfo. - -#define M_PKCS12_unpack_p7encdata(p7, pass, passlen) - -As above but for an encrypted content info. - -2.3 PKCS12 functions. - -M_PKCS12_unpack_authsafes(p12) - -Extract a STACK of authsafes from a PKCS12 structure. - -M_PKCS12_mac_present(p12) - -Check to see if a MAC is present. - -int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen) - -Verify a MAC on a PKCS12 structure. Returns an error if MAC not present. - - -Notes. - -1. All the function return 0 or NULL on error. -2. Encryption based functions take a common set of parameters. These are -described below. - -pass, passlen -ASCII password and length. The password on the MAC is called the "integrity -password" the encryption password is called the "privacy password" in the -PKCS#12 documentation. The passwords do not have to be the same. If -1 is -passed for the length it is worked out by the function itself (currently -this is sometimes done whatever is passed as the length but that may change). - -salt, saltlen -A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a -default length is used. - -iter -Iteration count. This is a measure of how many times an internal function is -called to encrypt the data. The larger this value is the longer it takes, it -makes dictionary attacks on passwords harder. NOTE: Some implementations do -not support an iteration count on the MAC. If the password for the MAC and -encryption is the same then there is no point in having a high iteration -count for encryption if the MAC has no count. The MAC could be attacked -and the password used for the main decryption. - -pbe_nid -This is the NID of the password based encryption method used. The following are -supported. -NID_pbe_WithSHA1And128BitRC4 -NID_pbe_WithSHA1And40BitRC4 -NID_pbe_WithSHA1And3_Key_TripleDES_CBC -NID_pbe_WithSHA1And2_Key_TripleDES_CBC -NID_pbe_WithSHA1And128BitRC2_CBC -NID_pbe_WithSHA1And40BitRC2_CBC - -Which you use depends on the implementation you are exporting to. "Export -grade" (i.e. cryptographically challenged) products cannot support all -algorithms. Typically you may be able to use any encryption on shrouded key -bags but they must then be placed in an unencrypted authsafe. Other authsafes -may only support 40bit encryption. Of course if you are using SSLeay -throughout you can strongly encrypt everything and have high iteration counts -on everything. - -3. For decryption routines only the password and length are needed. - -4. Unlike the external version the nid's of objects are the values of the -constants: that is NID_certBag is the real nid, therefore there is no -PKCS12_obj_offset() function. Note the object constants are not the same as -those of the external version. If you use these constants then you will need -to recompile your code. - -5. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or -macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be -reused or freed up safely. - diff --git a/openssl/doc/ssl/SSL_CIPHER_get_name.pod b/openssl/doc/ssl/SSL_CIPHER_get_name.pod deleted file mode 100644 index c598f4d..0000000 --- a/openssl/doc/ssl/SSL_CIPHER_get_name.pod +++ /dev/null @@ -1,132 +0,0 @@ -=pod - -=head1 NAME - -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); - -=head1 DESCRIPTION - -SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the -argument is the NULL pointer, a pointer to the constant value "NONE" is -returned. - -SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If -B<alg_bits> is not NULL, it contains the number of bits processed by the -chosen algorithm. If B<cipher> is NULL, 0 is returned. - -SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol -version that first defined the cipher. -This is currently B<SSLv2> or B<TLSv1/SSLv3>. -In some cases it should possibly return "TLSv1.2" but does not; -use SSL_CIPHER_description() instead. -If B<cipher> is NULL, "(NONE)" is returned. - -SSL_CIPHER_description() returns a textual description of the cipher used -into the buffer B<buf> of length B<len> provided. B<len> must be at least -128 bytes, otherwise a pointer to the string "Buffer too small" is -returned. If B<buf> is NULL, a buffer of 128 bytes is allocated using -OPENSSL_malloc(). If the allocation fails, a pointer to the string -"OPENSSL_malloc Error" is returned. - -=head1 NOTES - -The number of bits processed can be different from the secret bits. An -export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm -does use the full 128 bits (which would be returned for B<alg_bits>), of -which however 88bits are fixed. The search space is hence only 40 bits. - -The string returned by SSL_CIPHER_description() in case of success consists -of cleartext information separated by one or more blanks in the following -sequence: - -=over 4 - -=item <ciphername> - -Textual representation of the cipher name. - -=item <protocol version> - -Protocol version: B<SSLv2>, B<SSLv3>, B<TLSv1.2>. The TLSv1.0 ciphers are -flagged with SSLv3. No new ciphers were added by TLSv1.1. - -=item Kx=<key exchange> - -Key exchange method: B<RSA> (for export ciphers as B<RSA(512)> or -B<RSA(1024)>), B<DH> (for export ciphers as B<DH(512)> or B<DH(1024)>), -B<DH/RSA>, B<DH/DSS>, B<Fortezza>. - -=item Au=<authentication> - -Authentication method: B<RSA>, B<DSS>, B<DH>, B<None>. None is the -representation of anonymous ciphers. - -=item Enc=<symmetric encryption method> - -Encryption method with number of secret bits: B<DES(40)>, B<DES(56)>, -B<3DES(168)>, B<RC4(40)>, B<RC4(56)>, B<RC4(64)>, B<RC4(128)>, -B<RC2(40)>, B<RC2(56)>, B<RC2(128)>, B<IDEA(128)>, B<Fortezza>, B<None>. - -=item Mac=<message authentication code> - -Message digest: B<MD5>, B<SHA1>. - -=item <export flag> - -If the cipher is flagged exportable with respect to old US crypto -regulations, the word "B<export>" is printed. - -=back - -=head1 EXAMPLES - -Some examples for the output of SSL_CIPHER_description(): - - EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 - EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 - RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 - EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export - -A comp[lete list can be retrieved by invoking the following command: - - openssl ciphers -v ALL - -=head1 BUGS - -If SSL_CIPHER_description() is called with B<cipher> being NULL, the -library crashes. - -If SSL_CIPHER_description() cannot handle a built-in cipher, the according -description of the cipher property is B<unknown>. This case should not -occur. - -The standard terminology for ephemeral Diffie-Hellman schemes is DHE -(finite field) or ECDHE (elliptic curve). This version of OpenSSL -idiosyncratically reports these schemes as EDH and EECDH, even though -it also accepts the standard terminology. - -It is recommended to use the standard terminology (DHE and ECDHE) -during configuration (e.g. via SSL_CTX_set_cipher_list) for clarity of -configuration. OpenSSL versions after 1.0.2 will report the standard -terms via SSL_CIPHER_get_name and SSL_CIPHER_description. - -=head1 RETURN VALUES - -See DESCRIPTION - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_current_cipher(3)|SSL_get_current_cipher(3)>, -L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<ciphers(1)|ciphers(1)>, -L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_COMP_add_compression_method.pod b/openssl/doc/ssl/SSL_COMP_add_compression_method.pod deleted file mode 100644 index 2bb4403..0000000 --- a/openssl/doc/ssl/SSL_COMP_add_compression_method.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -SSL_COMP_add_compression_method, 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); - - +void SSL_COMP_free_compression_methods(void); - -=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_free_compression_methods() frees the internal table of -compression methods that were built internally, and possibly -augmented by adding SSL_COMP_add_compression_method(). - -=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 - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CONF_CTX_new.pod b/openssl/doc/ssl/SSL_CONF_CTX_new.pod deleted file mode 100644 index a9ccb04..0000000 --- a/openssl/doc/ssl/SSL_CONF_CTX_new.pod +++ /dev/null @@ -1,40 +0,0 @@ -=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>. - -=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)|SSL_CONF_CTX_set_flags(3)>, -L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>, -L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>, -L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>, -L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2 - -=cut diff --git a/openssl/doc/ssl/SSL_CONF_CTX_set1_prefix.pod b/openssl/doc/ssl/SSL_CONF_CTX_set1_prefix.pod deleted file mode 100644 index 7699018..0000000 --- a/openssl/doc/ssl/SSL_CONF_CTX_set1_prefix.pod +++ /dev/null @@ -1,49 +0,0 @@ -=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)|SSL_CONF_CTX_new(3)>, -L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>, -L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>, -L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>, -L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2 - -=cut diff --git a/openssl/doc/ssl/SSL_CONF_CTX_set_flags.pod b/openssl/doc/ssl/SSL_CONF_CTX_set_flags.pod deleted file mode 100644 index 4e34280..0000000 --- a/openssl/doc/ssl/SSL_CONF_CTX_set_flags.pod +++ /dev/null @@ -1,68 +0,0 @@ -=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_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)|SSL_CONF_CTX_new(3)>, -L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>, -L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>, -L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>, -L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2 - -=cut diff --git a/openssl/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod b/openssl/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod deleted file mode 100644 index 2049a53..0000000 --- a/openssl/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod +++ /dev/null @@ -1,47 +0,0 @@ -=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)|SSL_CONF_CTX_new(3)>, -L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>, -L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>, -L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)>, -L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2 - -=cut diff --git a/openssl/doc/ssl/SSL_CONF_cmd.pod b/openssl/doc/ssl/SSL_CONF_cmd.pod deleted file mode 100644 index e81d76a..0000000 --- a/openssl/doc/ssl/SSL_CONF_cmd.pod +++ /dev/null @@ -1,439 +0,0 @@ -=pod - -=head1 NAME - -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: it does not currently use the B<-cert> file. - -=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_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> - -Disables protocol support for SSLv2, SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2 -by setting the corresponding options B<SSL_OP_NO_SSLv2>, B<SSL_OP_NO_SSLv3>, -B<SSL_OP_NO_TLSv1>, B<SSL_OP_NO_TLSv1_1> and B<SSL_OP_NO_TLSv1_2> respectively. - -=item B<-bugs> - -Various bug workarounds are set, same as setting B<SSL_OP_ALL>. - -=item B<-no_comp> - -Disables support for SSL/TLS compression, same as setting B<SSL_OP_NO_COMPRESS>. - -=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>. - -=item B<-debug_broken_protocol> - -disables various checks and permits several kinds of broken protocol behaviour -for testing purposes: it should B<NEVER> be used in anything other than a test -environment. Only supported if OpenSSL is configured with -B<-DOPENSSL_SSL_DEBUG_BROKEN_PROTOCOL>. - -=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 and 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<-key> option is set then a private key is -not loaded: it does not currently use the B<Certificate> file. - -=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<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<ECDHParameters> - -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<Automatic> 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<Protocol> - -The supported versions of the SSL or TLS protocol. - -The B<value> argument is a comma separated list of supported protocols to -enable or disable. If an protocol is preceded by B<-> that version is disabled. -Currently supported protocol values are B<SSLv2>, B<SSLv3>, B<TLSv1>, -B<TLSv1.1> and B<TLSv1.2>. -All protocol versions other than B<SSLv2> are enabled by default. -To avoid inadvertent enabling of B<SSLv2>, when SSLv2 is disabled, it is not -possible to enable it via the B<Protocol> command. - -=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 -B<SSL_CTX_set_options> 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. - -=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. - -=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"); - -then 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 is 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"); - -Enable all protocols except SSLv3 and SSLv2: - - SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3,-SSLv2"); - -Only enable TLSv1.2: - - SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2"); - -Disable TLS session tickets: - - SSL_CONF_cmd(ctx, "Options", "-SessionTicket"); - -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)|SSL_CONF_CTX_new(3)>, -L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>, -L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>, -L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>, -L<SSL_CONF_cmd_argv(3)|SSL_CONF_cmd_argv(3)> - -=head1 HISTORY - -SSL_CONF_cmd() was first added to OpenSSL 1.0.2 - -=cut diff --git a/openssl/doc/ssl/SSL_CONF_cmd_argv.pod b/openssl/doc/ssl/SSL_CONF_cmd_argv.pod deleted file mode 100644 index 6e66441..0000000 --- a/openssl/doc/ssl/SSL_CONF_cmd_argv.pod +++ /dev/null @@ -1,42 +0,0 @@ -=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)|SSL_CONF_CTX_new(3)>, -L<SSL_CONF_CTX_set_flags(3)|SSL_CONF_CTX_set_flags(3)>, -L<SSL_CONF_CTX_set1_prefix(3)|SSL_CONF_CTX_set1_prefix(3)>, -L<SSL_CONF_CTX_set_ssl_ctx(3)|SSL_CONF_CTX_set_ssl_ctx(3)>, -L<SSL_CONF_cmd(3)|SSL_CONF_cmd(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2 - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_add1_chain_cert.pod b/openssl/doc/ssl/SSL_CTX_add1_chain_cert.pod deleted file mode 100644 index b999f09..0000000 --- a/openssl/doc/ssl/SSL_CTX_add1_chain_cert.pod +++ /dev/null @@ -1,150 +0,0 @@ -=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)|SSL_CTX_add_extra_chain_cert(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod deleted file mode 100644 index 04300fb..0000000 --- a/openssl/doc/ssl/SSL_CTX_add_extra_chain_cert.pod +++ /dev/null @@ -1,71 +0,0 @@ -=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)|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)|ssl(3)>, -L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, -L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, -L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> -L<SSL_CTX_set0_chain(3)|SSL_CTX_set0_chain(3)> -L<SSL_CTX_set1_chain(3)|SSL_CTX_set1_chain(3)> -L<SSL_CTX_add0_chain_cert(3)|SSL_CTX_add0_chain_cert(3)> -L<SSL_CTX_add1_chain_cert(3)|SSL_CTX_add1_chain_cert(3)> -L<SSL_set0_chain(3)|SSL_set0_chain(3)> -L<SSL_set1_chain(3)|SSL_set1_chain(3)> -L<SSL_add0_chain_cert(3)|SSL_add0_chain_cert(3)> -L<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)> -L<SSL_CTX_build_cert_chain(3)|SSL_CTX_build_cert_chain(3)> -L<SSL_build_cert_chain(3)|SSL_build_cert_chain(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_add_session.pod b/openssl/doc/ssl/SSL_CTX_add_session.pod deleted file mode 100644 index c660a18..0000000 --- a/openssl/doc/ssl/SSL_CTX_add_session.pod +++ /dev/null @@ -1,73 +0,0 @@ -=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_SESSION_free(3)>. - -SSL_CTX_remove_session() removes the session B<c> from the context B<ctx>. -L<SSL_SESSION_free(3)|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)|ssl(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_ctrl.pod b/openssl/doc/ssl/SSL_CTX_ctrl.pod deleted file mode 100644 index fb6adcf..0000000 --- a/openssl/doc/ssl/SSL_CTX_ctrl.pod +++ /dev/null @@ -1,34 +0,0 @@ -=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)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_flush_sessions.pod b/openssl/doc/ssl/SSL_CTX_flush_sessions.pod deleted file mode 100644 index 148c36c..0000000 --- a/openssl/doc/ssl/SSL_CTX_flush_sessions.pod +++ /dev/null @@ -1,49 +0,0 @@ -=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)|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)|SSL_CTX_sess_set_get_cb(3)>). - -=head1 RETURN VALUES - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, -L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_free.pod b/openssl/doc/ssl/SSL_CTX_free.pod deleted file mode 100644 index 51d8676..0000000 --- a/openssl/doc/ssl/SSL_CTX_free.pod +++ /dev/null @@ -1,41 +0,0 @@ -=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 -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. - -=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)|SSL_CTX_new(3)>, L<ssl(3)|ssl(3)>, -L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_get0_param.pod b/openssl/doc/ssl/SSL_CTX_get0_param.pod deleted file mode 100644 index ba16b50..0000000 --- a/openssl/doc/ssl/SSL_CTX_get0_param.pod +++ /dev/null @@ -1,55 +0,0 @@ -=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)|X509_VERIFY_PARAM_set_flags(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod b/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod deleted file mode 100644 index 0c40a91..0000000 --- a/openssl/doc/ssl/SSL_CTX_get_ex_new_index.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg); - - void *SSL_CTX_get_ex_data(const SSL_CTX *ctx, int idx); - - typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -SSL_CTX_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_CTX_set_ex_data() is used to store application data at B<arg> for B<idx> -into the B<ctx> object. - -SSL_CTX_get_ex_data() is used to retrieve the information for B<idx> from -B<ctx>. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod b/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod deleted file mode 100644 index 2a3747e..0000000 --- a/openssl/doc/ssl/SSL_CTX_get_verify_mode.pod +++ /dev/null @@ -1,50 +0,0 @@ -=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)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod b/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod deleted file mode 100644 index d1d8977..0000000 --- a/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod +++ /dev/null @@ -1,124 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_load_verify_locations - 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); - -=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. - -=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)|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)|SSL_CTX_add_extra_chain_cert(3)>, -L<SSL_CTX_use_certificate(3)|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 - -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 - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, -L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, -L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, -L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, -L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, -L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_new.pod b/openssl/doc/ssl/SSL_CTX_new.pod deleted file mode 100644 index b8cc879..0000000 --- a/openssl/doc/ssl/SSL_CTX_new.pod +++ /dev/null @@ -1,174 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_new, -SSLv23_method, SSLv23_server_method, SSLv23_client_method, -TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, -TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, -TLSv1_method, TLSv1_server_method, TLSv1_client_method, -SSLv3_method, SSLv3_server_method, SSLv3_client_method, -SSLv2_method, SSLv2_server_method, SSLv2_client_method, -DTLS_method, DTLS_server_method, DTLS_client_method, -DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method, -DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method - -create a new SSL_CTX object as framework for TLS/SSL enabled functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); - const SSL_METHOD *SSLv23_method(void); - const SSL_METHOD *SSLv23_server_method(void); - const SSL_METHOD *SSLv23_client_method(void); - const SSL_METHOD *TLSv1_2_method(void); - const SSL_METHOD *TLSv1_2_server_method(void); - const SSL_METHOD *TLSv1_2_client_method(void); - const SSL_METHOD *TLSv1_1_method(void); - const SSL_METHOD *TLSv1_1_server_method(void); - const SSL_METHOD *TLSv1_1_client_method(void); - const SSL_METHOD *TLSv1_method(void); - const SSL_METHOD *TLSv1_server_method(void); - const SSL_METHOD *TLSv1_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_SSL2 - const SSL_METHOD *SSLv2_method(void); - const SSL_METHOD *SSLv2_server_method(void); - const SSL_METHOD *SSLv2_client_method(void); - #endif - - const SSL_METHOD *DTLS_method(void); - const SSL_METHOD *DTLS_server_method(void); - const SSL_METHOD *DTLS_client_method(void); - const SSL_METHOD *DTLSv1_2_method(void); - const SSL_METHOD *DTLSv1_2_server_method(void); - const SSL_METHOD *DTLSv1_2_client_method(void); - const SSL_METHOD *DTLSv1_method(void); - const SSL_METHOD *DTLSv1_server_method(void); - const SSL_METHOD *DTLSv1_client_method(void); - -=head1 DESCRIPTION - -SSL_CTX_new() creates a new B<SSL_CTX> object as framework to establish -TLS/SSL enabled connections. - -=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 SSLv23_method(), SSLv23_server_method(), SSLv23_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 SSLv2, SSLv3, TLSv1, TLSv1.1 and TLSv1.2. -Most applications should use these method, and avoid the version specific -methods described below. - -The list of protocols available can be further limited using the -B<SSL_OP_NO_SSLv2>, 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. -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 SSLv2 and SSLv3 protocols are deprecated and should generally not be used. -Applications should typically use L<SSL_CTX_set_options(3)> in combination with -the B<SSL_OP_NO_SSLv3> flag to disable negotiation of SSLv3 via the above -I<version-flexible> SSL/TLS methods. -The B<SSL_OP_NO_SSLv2> option is set by default, and would need to be cleared -via L<SSL_CTX_clear_options(3)> in order to enable negotiation of SSLv2. - -=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. A client will send out TLSv1.2 client hello messages and -will also indicate that it only understand TLSv1.2. A server will only -understand TLSv1.2 client hello messages. - -=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. A client will send out TLSv1.1 client hello messages and -will also indicate that it only understand TLSv1.1. A server will only -understand TLSv1.1 client hello messages. - -=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() - -A TLS/SSL connection established with these methods will only understand the -TLSv1 protocol. A client will send out TLSv1 client hello messages and will -indicate that it only understands TLSv1. A server will only understand TLSv1 -client hello messages. - -=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() - -A TLS/SSL connection established with these methods will only understand the -SSLv3 protocol. A client will send out SSLv3 client hello messages and will -indicate that it only understands SSLv3. A server will only understand SSLv3 -client hello messages. The SSLv3 protocol is deprecated and should not be -used. - -=item SSLv2_method(), SSLv2_server_method(), SSLv2_client_method() - -A TLS/SSL connection established with these methods will only understand the -SSLv2 protocol. A client will send out SSLv2 client hello messages and will -also indicate that it only understand SSLv2. A server will only understand -SSLv2 client hello messages. The SSLv2 protocol offers little to no security -and should not be used. -As of OpenSSL 1.0.2g, EXPORT ciphers and 56-bit DES are no longer available -with SSLv2. - -=item DTLS_method(), DTLS_server_method(), DTLS_client_method() - -These are the version-flexible DTLS methods. - -=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 its default values. - -=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. - -=back - -=head1 SEE ALSO - -L<SSL_CTX_set_options(3)>, L<SSL_CTX_clear_options(3)>, L<SSL_set_options(3)>, -L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<ssl(3)|ssl(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_sess_number.pod b/openssl/doc/ssl/SSL_CTX_sess_number.pod deleted file mode 100644 index 19aa4e2..0000000 --- a/openssl/doc/ssl/SSL_CTX_sess_number.pod +++ /dev/null @@ -1,76 +0,0 @@ -=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)|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)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> -L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod deleted file mode 100644 index 4aeda09..0000000 --- a/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod +++ /dev/null @@ -1,53 +0,0 @@ -=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)|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)|ssl(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, -L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod deleted file mode 100644 index b9d54a4..0000000 --- a/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod +++ /dev/null @@ -1,87 +0,0 @@ -=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 *, 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, 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_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)|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)|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)|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)|SSL_SESSION_free(3)>. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, -L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, -L<SSL_CTX_free(3)|SSL_CTX_free(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_sessions.pod b/openssl/doc/ssl/SSL_CTX_sessions.pod deleted file mode 100644 index e05aab3..0000000 --- a/openssl/doc/ssl/SSL_CTX_sessions.pod +++ /dev/null @@ -1,34 +0,0 @@ -=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)|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)|lhash(3)> operations, so that the database must not be -modified directly but by using the -L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)> family of functions. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<lhash(3)|lhash(3)>, -L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set1_curves.pod b/openssl/doc/ssl/SSL_CTX_set1_curves.pod deleted file mode 100644 index 18d0c9a..0000000 --- a/openssl/doc/ssl/SSL_CTX_set1_curves.pod +++ /dev/null @@ -1,103 +0,0 @@ -=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, -SSL_CTX_set_ecdh_auto, SSL_set_ecdh_auto - 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); - - int SSL_CTX_set_ecdh_auto(SSL_CTX *ctx, int onoff); - int SSL_set_ecdh_auto(SSL *s, int onoff); - -=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. - -SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() set automatic curve -selection for server B<ctx> or B<ssl> to B<onoff>. If B<onoff> is 1 then -the highest preference curve is automatically used for ECDH temporary -keys used during key exchange. - -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. - -The functions SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() can be used to -make a server always choose the most appropriate curve for a client. If set -it will override any temporary ECDH parameters set by a server. Previous -versions of OpenSSL could effectively only use a single ECDH curve set -using a function such as SSL_CTX_set_ecdh_tmp(). Newer applications should -just call: - - SSL_CTX_set_ecdh_auto(ctx, 1); - -and they will automatically support ECDH using the most appropriate shared -curve. - -=head1 RETURN VALUES - -SSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves(), -SSL_set1_curves_list(), SSL_CTX_set_ecdh_auto() and SSL_set_ecdh_auto() -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)|SSL_CTX_add_extra_chain_cert(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set1_verify_cert_store.pod b/openssl/doc/ssl/SSL_CTX_set1_verify_cert_store.pod deleted file mode 100644 index 3e3a4fa..0000000 --- a/openssl/doc/ssl/SSL_CTX_set1_verify_cert_store.pod +++ /dev/null @@ -1,91 +0,0 @@ -=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)|SSL_CTX_add1_chain_cert(3)> or -L<SSL_CTX_add_extra_chain_cert(3)|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)|SSL_CTX_add_extra_chain_cert(3)> -L<SSL_CTX_set0_chain(3)|SSL_CTX_set0_chain(3)> -L<SSL_CTX_set1_chain(3)|SSL_CTX_set1_chain(3)> -L<SSL_CTX_add0_chain_cert(3)|SSL_CTX_add0_chain_cert(3)> -L<SSL_CTX_add1_chain_cert(3)|SSL_CTX_add1_chain_cert(3)> -L<SSL_set0_chain(3)|SSL_set0_chain(3)> -L<SSL_set1_chain(3)|SSL_set1_chain(3)> -L<SSL_add0_chain_cert(3)|SSL_add0_chain_cert(3)> -L<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)> -L<SSL_CTX_build_cert_chain(3)|SSL_CTX_build_cert_chain(3)> -L<SSL_build_cert_chain(3)|SSL_build_cert_chain(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.2. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/openssl/doc/ssl/SSL_CTX_set_alpn_select_cb.pod deleted file mode 100644 index 80ba8ab..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_alpn_select_cb.pod +++ /dev/null @@ -1,126 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, -SSL_select_next_proto, SSL_get0_alpn_selected - 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 protos_len); - int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos, - unsigned 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); - 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_alpn_selected(const SSL *ssl, const unsigned char **data, - unsigned int *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<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_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. - -=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_NOACK - -ALPN protocol not selected. - -=back - -=head1 SEE ALSO - -L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, -L<SSL_CTX_set_tlsext_servername_arg(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_cert_cb.pod b/openssl/doc/ssl/SSL_CTX_set_cert_cb.pod deleted file mode 100644 index 141d828..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_cert_cb.pod +++ /dev/null @@ -1,68 +0,0 @@ -=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 B<cert_cb()> callback, -B<arg> value is pointer which is passed to the application callback. - -When B<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)|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 supercedes 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)|ssl(3)>, L<SSL_use_certificate(3)|SSL_use_certificate(3)>, -L<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)>, -L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_cert_store.pod b/openssl/doc/ssl/SSL_CTX_set_cert_store.pod deleted file mode 100644 index 846416e..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_cert_store.pod +++ /dev/null @@ -1,64 +0,0 @@ -=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)|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)|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)|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)|ssl(3)>, -L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, -L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod deleted file mode 100644 index c0f4f85..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod +++ /dev/null @@ -1,75 +0,0 @@ -=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)|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)|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)|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 - -=head1 RETURN VALUES - -SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, -L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, -L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> - -=head1 HISTORY - -Previous to OpenSSL 0.9.7, the I<arg> argument to B<SSL_CTX_set_cert_verify_callback> -was ignored, and I<callback> was called simply as - int (*callback)(X509_STORE_CTX *) -To compile software written for previous versions of OpenSSL, a dummy -argument will have to be added to I<callback>. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod b/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod deleted file mode 100644 index c84a831..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_cipher_list.pod +++ /dev/null @@ -1,74 +0,0 @@ -=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)|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. 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 export ciphers with a keylength of 512 bits for the RSA key require -a temporary 512 bit RSA key, as typically the supplied key has a length -of 1024 bit (see -L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>). -RSA ciphers using DHE need a certificate and key and additional DH-parameters -(see L<SSL_CTX_set_tmp_dh_callback(3)|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)|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 a 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. - -If the cipher list does not contain any SSLv2 cipher suites (this is the -default) then SSLv2 is effectively disabled and neither clients nor servers -will attempt to use SSLv2. - -=head1 RETURN VALUES - -SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher -could be selected and 0 on complete failure. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, -L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, -L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, -L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, -L<ciphers(1)|ciphers(1)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod b/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod deleted file mode 100644 index 4965385..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_client_CA_list.pod +++ /dev/null @@ -1,94 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, -SSL_add_client_CA - set list of CAs sent to the client when requesting a -client certificate - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); - void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); - int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); - int SSL_add_client_CA(SSL *ssl, X509 *cacert); - -=head1 DESCRIPTION - -SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when -requesting a client certificate for B<ctx>. - -SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when -requesting a client certificate for the chosen B<ssl>, overriding the -setting valid for B<ssl>'s SSL_CTX object. - -SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the -list of CAs sent to the client when requesting a client certificate for -B<ctx>. - -SSL_add_client_CA() adds the CA name extracted from B<cacert> to the -list of CAs sent to the client when requesting a client certificate for -the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object. - -=head1 NOTES - -When a TLS/SSL server requests a client certificate (see -B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which -it will accept certificates, to the client. - -This list must explicitly be set using SSL_CTX_set_client_CA_list() for -B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list -specified overrides the previous setting. The CAs listed do not become -trusted (B<list> only contains the names, not the complete certificates); use -L<SSL_CTX_load_verify_locations(3)|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)|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)|ssl(3)>, -L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, -L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, -L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod deleted file mode 100644 index d0df69a..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod +++ /dev/null @@ -1,94 +0,0 @@ -=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 B<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 B<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)|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)|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)|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)|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)|SSL_clear(3)> is being called. It is therefore -mandatory to destroy the SSL object using L<SSL_free(3)|SSL_free(3)> -and create a new one to return to the previous state. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, -L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, -L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_custom_cli_ext.pod b/openssl/doc/ssl/SSL_CTX_set_custom_cli_ext.pod deleted file mode 100644 index 3fceef9..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_custom_cli_ext.pod +++ /dev/null @@ -1,133 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext - 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. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod deleted file mode 100644 index 2b87f01..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_default_passwd_cb.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set 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); - - int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata); - -=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 B<userdata> which -will be provided to the password callback on invocation. - -The pem_passwd_cb(), which must be provided by the application, hands back the -password to be used during decryption. On invocation a pointer to B<userdata> -is provided. The pem_passwd_cb must write 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). - -=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 pem_passwd_cb() 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 B<userdata> storage and the -pem_passwd_cb() only returns the password already stored. - -When asking for the password interactively, pem_passwd_cb() 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 - -SSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata() -do not provide diagnostic information. - -=head1 EXAMPLES - -The following example returns the password provided as B<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 pem_passwd_cb(char *buf, int size, int rwflag, void *password) - { - strncpy(buf, (char *)(password), size); - buf[size - 1] = '\0'; - return(strlen(buf)); - } - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, -L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod b/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod deleted file mode 100644 index 798e844..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod +++ /dev/null @@ -1,150 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, SSL_has_matching_session_id - 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 16 bytes for SSLv2 sessions and between -1 and 32 bytes for SSLv3/TLSv1. 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. - -If a SSLv2 session id is generated and B<id_len> is reduced, it will be -restored after the callback has finished and the session id will be padded -with 0x00. It is not recommended to change the B<id_len> for SSLv2 sessions. -The callback can use the L<SSL_get_version(3)|SSL_get_version(3)> function -to check, whether the session is of type SSLv2. - -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^128 possible ids -for an SSLv2 session, 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. - -When calling SSL_has_matching_session_id() for an SSLv2 session with -reduced B<id_len>, the match operation will be performed using the -fixed length required and with a 0x00 padded id. - -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; - const char *version; - - version = SSL_get_version(ssl); - if (!strcmp(version, "SSLv2")) - /* we must not change id_len */; - - 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(3)|ssl(3)>, L<SSL_get_version(3)|SSL_get_version(3)> - -=head1 HISTORY - -SSL_CTX_set_generate_session_id(), SSL_set_generate_session_id() -and SSL_has_matching_session_id() have been introduced in -OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_info_callback.pod b/openssl/doc/ssl/SSL_CTX_set_info_callback.pod deleted file mode 100644 index 0b4affd..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_info_callback.pod +++ /dev/null @@ -1,153 +0,0 @@ -=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, not 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)|SSL_state_string(3)> family of functions. - -The B<ret> information can be evaluated using the -L<SSL_alert_type_string(3)|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)|ssl(3)>, L<SSL_state_string(3)|SSL_state_string(3)>, -L<SSL_alert_type_string(3)|SSL_alert_type_string(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod b/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod deleted file mode 100644 index da68cb9..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod +++ /dev/null @@ -1,77 +0,0 @@ -=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 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)|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)|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)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, -L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> - -=head1 HISTORY - -SSL*_set/get_max_cert_list() have been introduced in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_mode.pod b/openssl/doc/ssl/SSL_CTX_set_mode.pod deleted file mode 100644 index 2a5aaa5..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_mode.pod +++ /dev/null @@ -1,101 +0,0 @@ -=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)|SSL_read(3)> or L<SSL_write(3)|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. Released memory is -either appended to a list of unused RAM chunks on the SSL_CTX, or simply -freed if the list of unused chunks would become longer than -SSL_CTX->freelist_max_len, which defaults to 32. Using this flag can -save around 34k per idle SSL connection. -This flag has no effect on SSL v2 connections, or on DTLS connections. - -=item SSL_MODE_SEND_FALLBACK_SCSV - -Send TLS_FALLBACK_SCSV in the ClientHello. -To be set only by applications that reconnect with a downgraded protocol -version; see draft-ietf-tls-downgrade-scsv-00 for details. - -DO NOT ENABLE THIS if your application attempts a normal handshake. -Only use this in explicit fallback retries, following the guidance -in draft-ietf-tls-downgrade-scsv-00. - -=back - -=head1 RETURN VALUES - -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)|ssl(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_write(3)|SSL_write(3)> - -=head1 HISTORY - -SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod b/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod deleted file mode 100644 index 8b82d94..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod +++ /dev/null @@ -1,99 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_get_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_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)|ssl(3)>, L<SSL_new(3)|SSL_new(3)> - -=head1 HISTORY - -SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), -SSL_set_msg_callback() and SSL_get_msg_callback_arg() were added in OpenSSL 0.9.7. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_options.pod b/openssl/doc/ssl/SSL_CTX_set_options.pod deleted file mode 100644 index 9a7e98c..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_options.pod +++ /dev/null @@ -1,355 +0,0 @@ -=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 - -Note: all these functions are implemented using macros. - -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. - -=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 logical 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)|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_MICROSOFT_SESS_ID_BUG - -www.microsoft.com - when talking SSLv2, if session-id reuse is -performed, the session-id passed back in the server-finished message -is different from the one decided upon. - -=item SSL_OP_NETSCAPE_CHALLENGE_BUG - -Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte -challenge but then appears to only use 16 bytes when generating the -encryption keys. Using 16 bytes is ok but it should be ok to use 32. -According to the SSLv3 spec, one should use 32 bytes for the challenge -when operating in SSLv2/v3 compatibility mode, but as mentioned above, -this breaks this server so 16 bytes is the way to go. - -=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG - -As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect. - -=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_TLS_BLOCK_PADDING_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)|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)|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 SSLv3/TLSv1 server will choose following its -own preferences. Because of the different protocol, for SSLv2 the server -will send its list of preferences to the client and the client chooses. - -=item SSL_OP_PKCS1_CHECK_1 - -... - -=item SSL_OP_PKCS1_CHECK_2 - -... - -=item SSL_OP_NETSCAPE_CA_DN_BUG - -If we accept a netscape connection, demand a client cert, have a -non-self-signed CA which does not have its CA in netscape, and the -browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta - -=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG - -... - -=item SSL_OP_NO_SSLv2 - -Do not use the SSLv2 protocol. -As of OpenSSL 1.0.2g the B<SSL_OP_NO_SSLv2> option is set by default. - -=item SSL_OP_NO_SSLv3 - -Do not use the SSLv3 protocol. -It is recommended that applications should set this option. - -=item SSL_OP_NO_TLSv1 - -Do not use the TLSv1 protocol. - -=item SSL_OP_NO_TLSv1_1 - -Do not use the TLSv1.1 protocol. - -=item SSL_OP_NO_TLSv1_2 - -Do not use the TLSv1.2 protocol. - -=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. - -=back - -=head1 SECURE RENEGOTIATION - -OpenSSL 0.9.8m and later always attempts to use secure renegotiation as -described in RFC5746. This counters the prefix attack described in -CVE-2009-3555 and elsewhere. - -The deprecated and highly broken SSLv2 protocol does not support -renegotiation at all: its use is B<strongly> discouraged. - -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. - -B<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are -unpatched) will result in the connection hanging if it receives a -B<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard -a B<no_renegotiation> alert as fatal and respond with a fatal -B<handshake_failure> alert. This is because the OpenSSL API currently has -no provision to indicate to an application that a renegotiation attempt -was refused. - -=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)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, -L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, -L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, -L<dhparam(1)|dhparam(1)> - -=head1 HISTORY - -B<SSL_OP_CIPHER_SERVER_PREFERENCE> and -B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> have been added in -OpenSSL 0.9.7. - -B<SSL_OP_TLS_ROLLBACK_BUG> has been added in OpenSSL 0.9.6 and was automatically -enabled with B<SSL_OP_ALL>. As of 0.9.7, it is no longer included in B<SSL_OP_ALL> -and must be explicitly set. - -B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. -Versions up to OpenSSL 0.9.6c do not include the countermeasure that -can be disabled with this option (in OpenSSL 0.9.6d, it was always -enabled). - -SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL -0.9.8m. - -B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT> -and the function SSL_get_secure_renegotiation_support() were first added in -OpenSSL 0.9.8m. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_psk_client_callback.pod b/openssl/doc/ssl/SSL_CTX_set_psk_client_callback.pod deleted file mode 100644 index 573f89a..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_psk_client_callback.pod +++ /dev/null @@ -1,81 +0,0 @@ -=pod - -=begin comment - -Copyright 2005 Nokia. All rights reserved. - -The portions of the attached software ("Contribution") is developed by -Nokia Corporation and is licensed pursuant to the OpenSSL open source -license. - -The Contribution, originally written by Mika Kousa and Pasi Eronen of -Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites -support (see RFC 4279) to OpenSSL. - -No patent licenses or other rights except those expressly stated in -the OpenSSL open source license shall be deemed granted or received -expressly, by implication, estoppel, or otherwise. - -No assurances are provided by Nokia that the Contribution does not -infringe the patent or other intellectual property rights of any third -party or that the license provides you with all the necessary rights -to make use of the Contribution. - -THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN -ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA -SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY -OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR -OTHERWISE. - -=end comment - -=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 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. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod deleted file mode 100644 index 393f8ff..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_quiet_shutdown.pod +++ /dev/null @@ -1,63 +0,0 @@ -=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)|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)|SSL_free(3)> or SSL_set_quiet_shutdown() is called again. -It is not changed when L<SSL_clear(3)|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)|SSL_shutdown(3)> -for a clean shutdown. - -When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)|SSL_shutdown(3)> -will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. -(L<SSL_shutdown(3)|SSL_shutdown(3)> then behaves like -L<SSL_set_shutdown(3)|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)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>, -L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, L<SSL_new(3)|SSL_new(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_read_ahead.pod b/openssl/doc/ssl/SSL_CTX_set_read_ahead.pod deleted file mode 100644 index 527164b..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_read_ahead.pod +++ /dev/null @@ -1,51 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_read_ahead, SSL_CTX_set_default_read_ahead, SSL_CTX_get_read_ahead, -SSL_CTX_get_default_read_ahead, SSL_set_read_ahead, SSL_get_read_ahead -- manage whether to read as many input bytes as possible - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_read_ahead(const SSL *s); - void SSL_set_read_ahead(SSL *s, int yes); - - #define SSL_CTX_get_default_read_ahead(ctx) - #define SSL_CTX_set_default_read_ahead(ctx,m) - #define SSL_CTX_get_read_ahead(ctx) - #define SSL_CTX_set_read_ahead(ctx,m) - -=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 a synonym for SSL_CTX_set_read_ahead, and -SSL_CTX_get_default_read_ahead is a synonym for SSL_CTX_get_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. - -=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)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod deleted file mode 100644 index 4d71f85..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod +++ /dev/null @@ -1,137 +0,0 @@ -=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)|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)|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)|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)|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)|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)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, -L<SSL_session_reused(3)|SSL_session_reused(3)>, -L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, -L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, -L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, -L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, -L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, -L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, -L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> - -=head1 HISTORY - -SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL -were introduced in OpenSSL 0.9.6h. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod b/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod deleted file mode 100644 index 7c9e515..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_session_id_context.pod +++ /dev/null @@ -1,83 +0,0 @@ -=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)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod b/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod deleted file mode 100644 index e254f96..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_ssl_version.pod +++ /dev/null @@ -1,61 +0,0 @@ -=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)|SSL_new(3)> are not affected, except when -L<SSL_clear(3)|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)|SSL_CTX_new(3)>. - -When L<SSL_clear(3)|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)|SSL_CTX_new(3)>, L<SSL_new(3)|SSL_new(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<ssl(3)|ssl(3)>, -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_timeout.pod b/openssl/doc/ssl/SSL_CTX_set_timeout.pod deleted file mode 100644 index e3de27c..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_timeout.pod +++ /dev/null @@ -1,59 +0,0 @@ -=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)|SSL_SESSION_get_time(3)> family of functions. - -Expired sessions are removed from the internal session cache, whenever -L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> is called, either -directly by the application or automatically (see -L<SSL_CTX_set_session_cache_mode(3)|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)|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)|ssl(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, -L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, -L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod b/openssl/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod deleted file mode 100644 index b8147ba..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_tlsext_status_cb, SSL_CTX_set_tlsext_status_arg, -SSL_set_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_set_tlsext_status_arg(SSL_CTX *ctx, void *arg); - - long SSL_set_tlsext_status_type(SSL *s, int type); - - 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_set_tlsext_status_type() function 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. 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 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_set_tlsext_status_type() and SSL_set_tlsext_status_ocsp_resp() return 0 on -error or 1 on success. - -SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data -or -1 if there is no OCSP response data. - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod b/openssl/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod deleted file mode 100644 index da0dd0f..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod +++ /dev/null @@ -1,195 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing - -=head1 SYNOPSIS - - #include <openssl/tls1.h> - - long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx, - int (*cb)(SSL *s, unsigned char key_name[16], - unsigned char iv[EVP_MAX_IV_LENGTH], - EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)); - -=head1 DESCRIPTION - -SSL_CTX_set_tlsext_ticket_key_cb() sets a callback fuction I<cb> for handling -session tickets for the ssl context I<sslctx>. Session tickets, defined in -RFC5077 provide an enhanced session resumption capability where the server -implementation is not required to maintain per session state. It only applies -to TLS and there is no SSLv3 implementation. - -The callback is available when the OpenSSL library was built without -I<OPENSSL_NO_TLSEXT> being defined. - -The callback function I<cb> will be called for every client instigated TLS -session when session ticket extension is presented in the TLS hello -message. It is the responsibility of this function to create or retrieve the -cryptographic parameters and to maintain their state. - -The OpenSSL library uses your callback function to help implement a common TLS -ticket construction state according to RFC5077 Section 4 such that per session -state is unnecessary and a small set of cryptographic variables needs to be -maintained by the callback function implementation. - -In order to reuse a session, a TLS client must send the a session ticket -extension to the server. The client can only send exactly one session ticket. -The server, through the callback function, either agrees to reuse the session -ticket information or it starts a full TLS handshake to create a new session -ticket. - -Before the callback function is started I<ctx> and I<hctx> have been -initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively. - -For new sessions tickets, when the client doesn't present a session ticket, or -an attempted retreival of the ticket failed, or a renew option was indicated, -the callback function will be called with I<enc> equal to 1. The OpenSSL -library expects that the function will set an arbitary I<name>, initialize -I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>. - -The I<name> is 16 characters long and is used as a key identifier. - -The I<iv> length is the length of the IV of the corresponding cipher. The -maximum IV length is L<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>. - -The initialization vector I<iv> should be a random value. The cipher context -I<ctx> should use the initialisation vector I<iv>. The cipher context can be -set using L<EVP_EncryptInit_ex>. The hmac context can be set using L<HMAC_Init_ex>. - -When the client presents a session ticket, the callback function with be called -with I<enc> set to 0 indicating that the I<cb> function should retreive a set -of parameters. In this case I<name> and I<iv> have already been parsed out of -the session ticket. The OpenSSL library expects that the I<name> will be used -to retrieve a cryptographic parameters and that the cryptographic context -I<ctx> will be set with the retreived parameters and the initialization vector -I<iv>. using a function like L<EVP_DecryptInit_ex>. The I<hctx> needs to be set -using L<HMAC_Init_ex>. - -If the I<name> is still valid but a renewal of the ticket is required the -callback function should return 2. The library will call the callback again -with an arguement of enc equal to 1 to set the new ticket. - -The return value of the I<cb> function is used by OpenSSL to determine what -further processing will occur. The following return values have meaning: - -=over 4 - -=item Z<>2 - -This indicates that the I<ctx> and I<hctx> have been set and the session can -continue on those parameters. Additionally it indicates that the session -ticket is in a renewal period and should be replaced. The OpenSSL library will -call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077 -3.3 paragraph 2). - -=item Z<>1 - -This indicates that the I<ctx> and I<hctx> have been set and the session can -continue on those parameters. - -=item Z<>0 - -This indicates that it was not possible to set/retrieve a session ticket and -the SSL/TLS session will continue by by negiotationing a set of cryptographic -parameters or using the alternate SSL/TLS resumption mechanism, session ids. - -If called with enc equal to 0 the library will call the I<cb> again to get -a new set of parameters. - -=item less than 0 - -This indicates an error. - -=back - -=head1 NOTES - -Session resumption shortcuts the TLS so that the client certificate -negiotation don't occur. It makes up for this by storing client certificate -an all other negotiated state information encrypted within the ticket. In a -resumed session the applications will have all this state information available -exactly as if a full negiotation had occured. - -If an attacker can obtain the key used to encrypt a session ticket, they can -obtain the master secret for any ticket using that key and decrypt any traffic -using that session: even if the ciphersuite supports forward secrecy. As -a result applications may wish to use multiple keys and avoid using long term -keys stored in files. - -Applications can use longer keys to maintain a consistent level of security. -For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key -the overall security is only 128 bits because breaking the ticket key will -enable an attacker to obtain the session keys. - -=head1 EXAMPLES - -Reference Implemention: - SSL_CTX_set_tlsext_ticket_key_cb(SSL,ssl_tlsext_ticket_key_cb); - .... - - static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc) - { - if (enc) { /* create new session */ - if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) { - return -1; /* insufficient random */ - } - - key = currentkey(); /* something that you need to implement */ - if ( !key ) { - /* current key doesn't exist or isn't valid */ - key = createkey(); /* something that you need to implement. - * createkey needs to initialise, a name, - * an aes_key, a hmac_key and optionally - * an expire time. */ - if ( !key ) { /* key couldn't be created */ - return 0; - } - } - memcpy(key_name, key->name, 16); - - EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv); - HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); - - return 1; - - } else { /* retrieve session */ - key = findkey(name); - - if (!key || key->expire < now() ) { - return 0; - } - - HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); - EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv ); - - if (key->expire < ( now() - RENEW_TIME ) ) { - /* return 2 - this session will get a new ticket even though the current is still valid */ - return 2; - } - return 1; - - } - } - - - -=head1 RETURN VALUES - -returns 0 to indicate the callback function was set. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, -L<SSL_session_reused(3)|SSL_session_reused(3)>, -L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, -L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, -L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, -L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, - -=head1 HISTORY - -This function was introduced in OpenSSL 0.9.8h - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod deleted file mode 100644 index 234fbc8..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod +++ /dev/null @@ -1,130 +0,0 @@ -=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)|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)|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. Files dh1024.pem -and dh512.pem contain 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)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, -L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, -L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, -L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod b/openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod deleted file mode 100644 index 94c55b8..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod +++ /dev/null @@ -1,159 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys for ephemeral key exchange - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx, - RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); - long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa); - long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx); - - void SSL_set_tmp_rsa_callback(SSL_CTX *ctx, - RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); - long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa) - long SSL_need_tmp_rsa(SSL *ssl) - - RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength); - -=head1 DESCRIPTION - -SSL_CTX_set_tmp_rsa_callback() sets the callback function for B<ctx> to be -used when a temporary/ephemeral RSA key is required to B<tmp_rsa_callback>. -The callback is inherited by all SSL objects newly created from B<ctx> -with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected. - -SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be -B<rsa>. The key is inherited by all SSL objects newly created from B<ctx> -with <SSL_new(3)|SSL_new(3)>. Already created SSL objects are not affected. - -SSL_CTX_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed -for RSA-based strength-limited 'exportable' ciphersuites because a RSA key -with a keysize larger than 512 bits is installed. - -SSL_set_tmp_rsa_callback() sets the callback only for B<ssl>. - -SSL_set_tmp_rsa() sets the key only for B<ssl>. - -SSL_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed, -for RSA-based strength-limited 'exportable' ciphersuites because a RSA key -with a keysize larger than 512 bits is installed. - -These functions apply to SSL/TLS servers only. - -=head1 NOTES - -When using a cipher with RSA authentication, an ephemeral RSA key exchange -can take place. In this case the session data are negotiated using the -ephemeral/temporary RSA key and the RSA key supplied and certified -by the certificate chain is only used for signing. - -Under previous export restrictions, ciphers with RSA keys shorter (512 bits) -than the usual key length of 1024 bits were created. To use these ciphers -with RSA keys of usual length, an ephemeral key exchange must be performed, -as the normal (certified) key cannot be directly used. - -Using ephemeral RSA key exchange yields forward secrecy, as the connection -can only be decrypted, when the RSA key is known. By generating a temporary -RSA 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) RSA key, as this key was -used for signing only. The downside is that creating a RSA key is -computationally expensive. - -Additionally, the use of ephemeral RSA key exchange is only allowed in -the TLS standard, when the RSA key can be used for signing only, that is -for export ciphers. Using ephemeral RSA key exchange for other purposes -violates the standard and can break interoperability with clients. -It is therefore strongly recommended to not use ephemeral RSA key -exchange and use DHE (Ephemeral Diffie-Hellman) key exchange instead -in order to achieve forward secrecy (see -L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>). - -An application may either directly specify the key or can supply the key via a -callback function. The callback approach has the advantage, that the callback -may generate the key only in case it is actually needed. As the generation of a -RSA key is however costly, it will lead to a significant delay in the handshake -procedure. Another advantage of the callback function is that it can supply -keys of different size while the explicit setting of the key is only useful for -key size of 512 bits to satisfy the export restricted ciphers and does give -away key length if a longer key would be allowed. - -The B<tmp_rsa_callback> is called with the B<keylength> needed and -the B<is_export> information. The B<is_export> flag is set, when the -ephemeral RSA key exchange is performed with an export cipher. - -=head1 EXAMPLES - -Generate temporary RSA keys to prepare ephemeral RSA key exchange. As the -generation of a RSA key costs a lot of computer time, they saved for later -reuse. For demonstration purposes, two keys for 512 bits and 1024 bits -respectively are generated. - - ... - /* Set up ephemeral RSA stuff */ - RSA *rsa_512 = NULL; - RSA *rsa_1024 = NULL; - - rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL); - if (rsa_512 == NULL) - evaluate_error_queue(); - - rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL); - if (rsa_1024 == NULL) - evaluate_error_queue(); - - ... - - RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength) - { - RSA *rsa_tmp=NULL; - - switch (keylength) { - case 512: - if (rsa_512) - rsa_tmp = rsa_512; - else { /* generate on the fly, should not happen in this example */ - rsa_tmp = RSA_generate_key(keylength,RSA_F4,NULL,NULL); - rsa_512 = rsa_tmp; /* Remember for later reuse */ - } - break; - case 1024: - if (rsa_1024) - rsa_tmp=rsa_1024; - else - should_not_happen_in_this_example(); - break; - default: - /* Generating a key on the fly is very costly, so use what is there */ - if (rsa_1024) - rsa_tmp=rsa_1024; - else - rsa_tmp=rsa_512; /* Use at least a shorter key */ - } - return(rsa_tmp); - } - -=head1 RETURN VALUES - -SSL_CTX_set_tmp_rsa_callback() and SSL_set_tmp_rsa_callback() do not return -diagnostic output. - -SSL_CTX_set_tmp_rsa() and SSL_set_tmp_rsa() do return 1 on success and 0 -on failure. Check the error queue to find out the reason of failure. - -SSL_CTX_need_tmp_rsa() and SSL_need_tmp_rsa() return 1 if a temporary -RSA key is needed and 0 otherwise. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, -L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, -L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, -L<SSL_new(3)|SSL_new(3)>, L<ciphers(1)|ciphers(1)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_set_verify.pod b/openssl/doc/ssl/SSL_CTX_set_verify.pod deleted file mode 100644 index b6ba6bb..0000000 --- a/openssl/doc/ssl/SSL_CTX_set_verify.pod +++ /dev/null @@ -1,294 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, - int (*verify_callback)(int, X509_STORE_CTX *)); - void SSL_set_verify(SSL *s, int mode, - int (*verify_callback)(int, X509_STORE_CTX *)); - void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth); - void SSL_set_verify_depth(SSL *s, int depth); - - int verify_callback(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)|SSL_new(3)>. - -SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain -verification that shall be allowed for B<ctx>. (See the BUGS section.) - -SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain -verification that shall be allowed for B<ssl>. (See the BUGS section.) - -=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)|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 - -Exactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be -set at any time. - -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)|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 the limit up -to which depth certificates in a chain are used during the verification -procedure. If the certificate chain is longer than allowed, the certificates -above the limit are ignored. Error messages are generated as if these -certificates would not be present, most likely a -X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. -The depth count is "level 0:peer certificate", "level 1: CA certificate", -"level 2: higher level CA certificate", and so on. Setting the maximum -depth to 2 allows the levels 0, 1, and 2. The default depth limit is 100, -allowing for the peer certificate and additional 100 CA certificates. - -The B<verify_callback> function is used to control the behaviour when the -SSL_VERIFY_PEER flag is set. It must be supplied by the application and -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)|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 SSL_VERIFY_NONE is not set. This can lead to -unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not -used as required (exactly one must be set at any time). - -The certificate verification depth set with SSL[_CTX]_verify_depth() -stops the verification at a certain depth. The error message produced -will be that of an incomplete certificate chain and not -X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected. - -=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<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, -L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|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(ctx->current_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(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, -L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, -L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, -L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, -L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, -L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, -L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, -L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_use_certificate.pod b/openssl/doc/ssl/SSL_CTX_use_certificate.pod deleted file mode 100644 index 80321b8..0000000 --- a/openssl/doc/ssl/SSL_CTX_use_certificate.pod +++ /dev/null @@ -1,165 +0,0 @@ -=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_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_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)|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)|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)|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. -There is no corresponding function working on a single SSL object. - -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)|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)|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)|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)|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)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, -L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, -L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, -L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, -L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, -L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> - -=head1 HISTORY - -Support for DER encoded private keys (SSL_FILETYPE_ASN1) in -SSL_CTX_use_PrivateKey_file() and SSL_use_PrivateKey_file() was added -in 0.9.8 . - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod deleted file mode 100644 index 12db0da..0000000 --- a/openssl/doc/ssl/SSL_CTX_use_psk_identity_hint.pod +++ /dev/null @@ -1,106 +0,0 @@ -=pod - -=begin comment - -Copyright 2005 Nokia. All rights reserved. - -The portions of the attached software ("Contribution") is developed by -Nokia Corporation and is licensed pursuant to the OpenSSL open source -license. - -The Contribution, originally written by Mika Kousa and Pasi Eronen of -Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites -support (see RFC 4279) to OpenSSL. - -No patent licenses or other rights except those expressly stated in -the OpenSSL open source license shall be deemed granted or received -expressly, by implication, estoppel, or otherwise. - -No assurances are provided by Nokia that the Contribution does not -infringe the patent or other intellectual property rights of any third -party or that the license provides you with all the necessary rights -to make use of the Contribution. - -THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN -ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA -SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY -OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR -OTHERWISE. - -=end comment - -=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 - -=cut diff --git a/openssl/doc/ssl/SSL_CTX_use_serverinfo.pod b/openssl/doc/ssl/SSL_CTX_use_serverinfo.pod deleted file mode 100644 index caeb28d..0000000 --- a/openssl/doc/ssl/SSL_CTX_use_serverinfo.pod +++ /dev/null @@ -1,54 +0,0 @@ -=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 NOTES - -=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 SEE ALSO - -=head1 HISTORY - - -=cut diff --git a/openssl/doc/ssl/SSL_SESSION_free.pod b/openssl/doc/ssl/SSL_SESSION_free.pod deleted file mode 100644 index 110ec73..0000000 --- a/openssl/doc/ssl/SSL_SESSION_free.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_free - free an allocated SSL_SESSION structure - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_SESSION_free(SSL_SESSION *session); - -=head1 DESCRIPTION - -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. - -=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)|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)|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)|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)|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_free() does not provide diagnostic information. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, - L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod b/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod deleted file mode 100644 index 657cda9..0000000 --- a/openssl/doc/ssl/SSL_SESSION_get_ex_new_index.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_SESSION_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, void *arg); - - void *SSL_SESSION_get_ex_data(const SSL_SESSION *session, int idx); - - typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -SSL_SESSION_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_SESSION_set_ex_data() is used to store application data at B<arg> for B<idx> -into the B<session> object. - -SSL_SESSION_get_ex_data() is used to retrieve the information for B<idx> from -B<session>. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. - -=head1 WARNINGS - -The application data is only maintained for sessions held in memory. The -application data is not included when dumping the session with -i2d_SSL_SESSION() (and all functions indirectly calling the dump functions -like PEM_write_SSL_SESSION() and PEM_write_bio_SSL_SESSION()) and can -therefore not be restored. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_SESSION_get_time.pod b/openssl/doc/ssl/SSL_SESSION_get_time.pod deleted file mode 100644 index 490337a..0000000 --- a/openssl/doc/ssl/SSL_SESSION_get_time.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, SSL_SESSION_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)|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(3)|ssl(3)>, -L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, -L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_accept.pod b/openssl/doc/ssl/SSL_accept.pod deleted file mode 100644 index 89ad6bd..0000000 --- a/openssl/doc/ssl/SSL_accept.pod +++ /dev/null @@ -1,73 +0,0 @@ -=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)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, -L<SSL_do_handshake(3)|SSL_do_handshake(3)>, -L<SSL_CTX_new(3)|SSL_CTX_new(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_alert_type_string.pod b/openssl/doc/ssl/SSL_alert_type_string.pod deleted file mode 100644 index 0329c34..0000000 --- a/openssl/doc/ssl/SSL_alert_type_string.pod +++ /dev/null @@ -1,233 +0,0 @@ -=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)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_check_chain.pod b/openssl/doc/ssl/SSL_check_chain.pod deleted file mode 100644 index d3b7601..0000000 --- a/openssl/doc/ssl/SSL_check_chain.pod +++ /dev/null @@ -1,85 +0,0 @@ -=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)|SSL_CTX_set_cert_cb(3)>, -L<ssl(3)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_clear.pod b/openssl/doc/ssl/SSL_clear.pod deleted file mode 100644 index ba192bd..0000000 --- a/openssl/doc/ssl/SSL_clear.pod +++ /dev/null @@ -1,75 +0,0 @@ -=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)|SSL_shutdown(3)> was not called for the connection -or at least L<SSL_set_shutdown(3)|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 SSLv23_*_methods were chosen on startup. This -will might lead to connection failures (see L<SSL_new(3)|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)|SSL_get_session(3)>; -L<SSL_new(3)|SSL_new(3)>; -L<SSL_set_session(3)|SSL_set_session(3)>; -L<SSL_free(3)|SSL_free(3)> -instead to avoid such failures -(or simply L<SSL_free(3)|SSL_free(3)>; L<SSL_new(3)|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)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, -L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, L<ssl(3)|ssl(3)>, -L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_connect.pod b/openssl/doc/ssl/SSL_connect.pod deleted file mode 100644 index 68e2b82..0000000 --- a/openssl/doc/ssl/SSL_connect.pod +++ /dev/null @@ -1,73 +0,0 @@ -=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)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, -L<SSL_do_handshake(3)|SSL_do_handshake(3)>, -L<SSL_CTX_new(3)|SSL_CTX_new(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_do_handshake.pod b/openssl/doc/ssl/SSL_do_handshake.pod deleted file mode 100644 index 8b590c9..0000000 --- a/openssl/doc/ssl/SSL_do_handshake.pod +++ /dev/null @@ -1,72 +0,0 @@ -=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)|SSL_set_connect_state(3)> or -L<SSL_set_accept_state(3)|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)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, -L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_free.pod b/openssl/doc/ssl/SSL_free.pod deleted file mode 100644 index 13c1abd..0000000 --- a/openssl/doc/ssl/SSL_free.pod +++ /dev/null @@ -1,44 +0,0 @@ -=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. - -=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)|SSL_shutdown(3)> was not called for the connection -and L<SSL_set_shutdown(3)|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)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, -L<ssl(3)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_SSL_CTX.pod b/openssl/doc/ssl/SSL_get_SSL_CTX.pod deleted file mode 100644 index 659c482..0000000 --- a/openssl/doc/ssl/SSL_get_SSL_CTX.pod +++ /dev/null @@ -1,26 +0,0 @@ -=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)|SSL_new(3)>. - -=head1 RETURN VALUES - -The pointer to the SSL_CTX object is returned. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_ciphers.pod b/openssl/doc/ssl/SSL_get_ciphers.pod deleted file mode 100644 index aecadd9..0000000 --- a/openssl/doc/ssl/SSL_get_ciphers.pod +++ /dev/null @@ -1,42 +0,0 @@ -=pod - -=head1 NAME - -SSL_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); - 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_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() can be obtained using -the L<SSL_CIPHER_get_name(3)|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. - -=head1 RETURN VALUES - -See DESCRIPTION - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, -L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_client_CA_list.pod b/openssl/doc/ssl/SSL_get_client_CA_list.pod deleted file mode 100644 index 68181b2..0000000 --- a/openssl/doc/ssl/SSL_get_client_CA_list.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); - STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for -B<ctx> using L<SSL_CTX_set_client_CA_list(3)|SSL_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)|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)|ssl(3)>, -L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, -L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_current_cipher.pod b/openssl/doc/ssl/SSL_get_current_cipher.pod deleted file mode 100644 index e5ab124..0000000 --- a/openssl/doc/ssl/SSL_get_current_cipher.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name, -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); - #define SSL_get_cipher(s) \ - SSL_CIPHER_get_name(SSL_get_current_cipher(s)) - #define SSL_get_cipher_name(s) \ - SSL_CIPHER_get_name(SSL_get_current_cipher(s)) - #define SSL_get_cipher_bits(s,np) \ - SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np) - #define SSL_get_cipher_version(s) \ - SSL_CIPHER_get_version(SSL_get_current_cipher(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. - -SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the -name of the currently used cipher. 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. -See L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> for more details. - -=head1 RETURN VALUES - -SSL_get_current_cipher() returns the cipher actually used or NULL, when -no session has been established. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_default_timeout.pod b/openssl/doc/ssl/SSL_get_default_timeout.pod deleted file mode 100644 index a648a9b..0000000 --- a/openssl/doc/ssl/SSL_get_default_timeout.pod +++ /dev/null @@ -1,41 +0,0 @@ -=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)|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 (SSLv2, SSLv3, and TLSv1). - -=head1 RETURN VALUES - -See description. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, -L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, -L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_error.pod b/openssl/doc/ssl/SSL_get_error.pod deleted file mode 100644 index 2a93894..0000000 --- a/openssl/doc/ssl/SSL_get_error.pod +++ /dev/null @@ -1,112 +0,0 @@ -=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_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)|ssl(3)>, L<err(3)|err(3)> - -=head1 HISTORY - -SSL_get_error() was added in SSLeay 0.8. - -=cut diff --git a/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod b/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod deleted file mode 100644 index 165c6a5..0000000 --- a/openssl/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_ex_data_X509_STORE_CTX_idx - get ex_data index to access SSL structure -from X509_STORE_CTX - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_ex_data_X509_STORE_CTX_idx(void); - -=head1 DESCRIPTION - -SSL_get_ex_data_X509_STORE_CTX_idx() returns the index number under which -the pointer to the SSL object is stored into the X509_STORE_CTX object. - -=head1 NOTES - -Whenever a X509_STORE_CTX object is created for the verification of the -peers certificate during a handshake, a pointer to the SSL object is -stored into the X509_STORE_CTX object to identify the connection affected. -To retrieve this pointer the X509_STORE_CTX_get_ex_data() function can -be used with the correct index. This index is globally the same for all -X509_STORE_CTX objects and can be retrieved using -SSL_get_ex_data_X509_STORE_CTX_idx(). The index value is set when -SSL_get_ex_data_X509_STORE_CTX_idx() is first called either by the application -program directly or indirectly during other SSL setup functions or during -the handshake. - -The value depends on other index values defined for X509_STORE_CTX objects -before the SSL index is created. - -=head1 RETURN VALUES - -=over 4 - -=item E<gt>=0 - -The index value to access the pointer. - -=item E<lt>0 - -An error occurred, check the error stack for a detailed error message. - -=back - -=head1 EXAMPLES - -The index returned from SSL_get_ex_data_X509_STORE_CTX_idx() allows to -access the SSL object for the connection to be accessed during the -verify_callback() when checking the peers certificate. Please check -the example in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, -L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_ex_new_index.pod b/openssl/doc/ssl/SSL_get_ex_new_index.pod deleted file mode 100644 index 228d23d..0000000 --- a/openssl/doc/ssl/SSL_get_ex_new_index.pod +++ /dev/null @@ -1,59 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_set_ex_data(SSL *ssl, int idx, void *arg); - - void *SSL_get_ex_data(const SSL *ssl, int idx); - - typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -SSL_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_set_ex_data() is used to store application data at B<arg> for B<idx> into -the B<ssl> object. - -SSL_get_ex_data() is used to retrieve the information for B<idx> from -B<ssl>. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>. - -=head1 EXAMPLES - -An example on how to use the functionality is included in the example -verify_callback() in L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>, -L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_fd.pod b/openssl/doc/ssl/SSL_get_fd.pod deleted file mode 100644 index 89260b5..0000000 --- a/openssl/doc/ssl/SSL_get_fd.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_fd - 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)|SSL_set_fd(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_peer_cert_chain.pod b/openssl/doc/ssl/SSL_get_peer_cert_chain.pod deleted file mode 100644 index 059376c..0000000 --- a/openssl/doc/ssl/SSL_get_peer_cert_chain.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_peer_cert_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); - -=head1 DESCRIPTION - -SSL_get_peer_cert_chain() returns a pointer to STACK_OF(X509) certificates -forming the certificate chain of the peer. If called on the client side, -the stack also contains the peer's certificate; if called on the server -side, the peer's certificate must be obtained separately using -L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>. -If the peer did not present a certificate, NULL is returned. - -=head1 NOTES - -The peer certificate chain is not necessarily available after reusing -a session, in which case a NULL pointer is returned. - -The reference count of the STACK_OF(X509) object is not incremented. -If the corresponding session is freed, the pointer must not be used -any longer. - -=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)|ssl(3)>, L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_peer_certificate.pod b/openssl/doc/ssl/SSL_get_peer_certificate.pod deleted file mode 100644 index ef7c8be..0000000 --- a/openssl/doc/ssl/SSL_get_peer_certificate.pod +++ /dev/null @@ -1,55 +0,0 @@ -=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)|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)|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)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, -L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_psk_identity.pod b/openssl/doc/ssl/SSL_get_psk_identity.pod deleted file mode 100644 index fe62916..0000000 --- a/openssl/doc/ssl/SSL_get_psk_identity.pod +++ /dev/null @@ -1,63 +0,0 @@ -=pod - -=begin comment - -Copyright 2005 Nokia. All rights reserved. - -The portions of the attached software ("Contribution") is developed by -Nokia Corporation and is licensed pursuant to the OpenSSL open source -license. - -The Contribution, originally written by Mika Kousa and Pasi Eronen of -Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites -support (see RFC 4279) to OpenSSL. - -No patent licenses or other rights except those expressly stated in -the OpenSSL open source license shall be deemed granted or received -expressly, by implication, estoppel, or otherwise. - -No assurances are provided by Nokia that the Contribution does not -infringe the patent or other intellectual property rights of any third -party or that the license provides you with all the necessary rights -to make use of the Contribution. - -THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN -ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA -SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY -OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR -OTHERWISE. - -=end comment - -=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>. - -=cut diff --git a/openssl/doc/ssl/SSL_get_rbio.pod b/openssl/doc/ssl/SSL_get_rbio.pod deleted file mode 100644 index 3d98233..0000000 --- a/openssl/doc/ssl/SSL_get_rbio.pod +++ /dev/null @@ -1,40 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_rbio - 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)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_session.pod b/openssl/doc/ssl/SSL_get_session.pod deleted file mode 100644 index 0c41caa..0000000 --- a/openssl/doc/ssl/SSL_get_session.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_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)|SSL_clear(3)> or -L<SSL_free(3)|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)|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)|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 - -The return value points to the data of an SSL session. - -=back - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>, -L<SSL_clear(3)|SSL_clear(3)>, -L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_verify_result.pod b/openssl/doc/ssl/SSL_get_verify_result.pod deleted file mode 100644 index 55b56a5..0000000 --- a/openssl/doc/ssl/SSL_get_verify_result.pod +++ /dev/null @@ -1,57 +0,0 @@ -=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)|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)|verify(1)>. - -=back - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_set_verify_result(3)|SSL_set_verify_result(3)>, -L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, -L<verify(1)|verify(1)> - -=cut diff --git a/openssl/doc/ssl/SSL_get_version.pod b/openssl/doc/ssl/SSL_get_version.pod deleted file mode 100644 index 9ae6f25..0000000 --- a/openssl/doc/ssl/SSL_get_version.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_version - get the protocol version of a connection. - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - const char *SSL_get_version(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_version() returns the name of the protocol used for the -connection B<ssl>. - -=head1 RETURN VALUES - -The following strings can be returned: - -=over 4 - -=item SSLv2 - -The connection uses the SSLv2 protocol. - -=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)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_library_init.pod b/openssl/doc/ssl/SSL_library_init.pod deleted file mode 100644 index 8766776..0000000 --- a/openssl/doc/ssl/SSL_library_init.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -SSL_library_init, OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms -- initialize SSL library by registering algorithms - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_library_init(void); - #define OpenSSL_add_ssl_algorithms() SSL_library_init() - #define SSLeay_add_ssl_algorithms() SSL_library_init() - -=head1 DESCRIPTION - -SSL_library_init() registers the available SSL/TLS ciphers and digests. - -OpenSSL_add_ssl_algorithms() and SSLeay_add_ssl_algorithms() are synonyms -for SSL_library_init(). - -=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 EXAMPLES - -A typical TLS/SSL application will start with the library initialization, -and provide readable error messages. - - SSL_load_error_strings(); /* readable error messages */ - SSL_library_init(); /* initialize library */ - -=head1 RETURN VALUES - -SSL_library_init() always returns "1", so it is safe to discard the return -value. - -=head1 NOTES - -OpenSSL 0.9.8o and 1.0.0a and later added SHA2 algorithms to SSL_library_init(). -Applications which need to use SHA2 in earlier versions of OpenSSL should call -OpenSSL_add_all_algorithms() as well. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>, -L<RAND_add(3)|RAND_add(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_load_client_CA_file.pod b/openssl/doc/ssl/SSL_load_client_CA_file.pod deleted file mode 100644 index 02527dc..0000000 --- a/openssl/doc/ssl/SSL_load_client_CA_file.pod +++ /dev/null @@ -1,62 +0,0 @@ -=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)|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)|ssl(3)>, -L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_new.pod b/openssl/doc/ssl/SSL_new.pod deleted file mode 100644 index 25300e9..0000000 --- a/openssl/doc/ssl/SSL_new.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -SSL_new - create a new SSL structure for a connection - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - SSL *SSL_new(SSL_CTX *ctx); - -=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 (SSLv2/v3/TLSv1), -options, verification settings, timeout settings. - -=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. - -=back - -=head1 SEE ALSO - -L<SSL_free(3)|SSL_free(3)>, L<SSL_clear(3)|SSL_clear(3)>, -L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, -L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>, -L<ssl(3)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_pending.pod b/openssl/doc/ssl/SSL_pending.pod deleted file mode 100644 index 9dd071b..0000000 --- a/openssl/doc/ssl/SSL_pending.pod +++ /dev/null @@ -1,45 +0,0 @@ -=pod - -=head1 NAME - -SSL_pending - obtain number of readable bytes buffered in an SSL object - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_pending(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_pending() returns the number of bytes which are available inside -B<ssl> for immediate read. - -=head1 NOTES - -Data are received in blocks from the peer. Therefore data can be buffered -inside B<ssl> and are ready for immediate retrieval with -L<SSL_read(3)|SSL_read(3)>. - -=head1 RETURN VALUES - -The number of bytes pending is returned. - -=head1 BUGS - -SSL_pending() takes into account only bytes from the TLS/SSL record -that is currently being processed (if any). If the B<SSL> object's -I<read_ahead> flag is set (see -L<SSL_CTX_set_read_ahead(3)|SSL_CTX_set_read_ahead(3)>), additional protocol -bytes may have been read containing more TLS/SSL records; these are ignored by -SSL_pending(). - -Up to OpenSSL 0.9.6, SSL_pending() does not check if the record type -of pending data is application data. - -=head1 SEE ALSO - -L<SSL_read(3)|SSL_read(3)>, -L<SSL_CTX_set_read_ahead(3)|SSL_CTX_set_read_ahead(3)>, L<ssl(3)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_read.pod b/openssl/doc/ssl/SSL_read.pod deleted file mode 100644 index ef983c9..0000000 --- a/openssl/doc/ssl/SSL_read.pod +++ /dev/null @@ -1,120 +0,0 @@ -=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)|SSL_connect(3)> or -L<SSL_accept(3)|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)|SSL_set_connect_state(3)> or SSL_set_accept_state() -before the first call to an SSL_read() or L<SSL_write(3)|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)|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)|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)|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 - - -=item E<lt>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. - -SSLv2 (deprecated) does not support a shutdown alert protocol, so it can -only be detected, whether the underlying connection was closed. It cannot -be checked, whether the closure was initiated by the peer or by something -else. - -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)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, -L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, -L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, -L<SSL_pending(3)|SSL_pending(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, -L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_rstate_string.pod b/openssl/doc/ssl/SSL_rstate_string.pod deleted file mode 100644 index bdb8a1f..0000000 --- a/openssl/doc/ssl/SSL_rstate_string.pod +++ /dev/null @@ -1,59 +0,0 @@ -=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)|ssl(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_session_reused.pod b/openssl/doc/ssl/SSL_session_reused.pod deleted file mode 100644 index b09d8a7..0000000 --- a/openssl/doc/ssl/SSL_session_reused.pod +++ /dev/null @@ -1,45 +0,0 @@ -=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)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_set_bio.pod b/openssl/doc/ssl/SSL_set_bio.pod deleted file mode 100644 index 67c9756..0000000 --- a/openssl/doc/ssl/SSL_set_bio.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_bio - connect the SSL object with a BIO - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); - -=head1 DESCRIPTION - -SSL_set_bio() connects the BIOs B<rbio> and B<wbio> for the read and write -operations of the TLS/SSL (encrypted) side of B<ssl>. - -The SSL engine inherits the behaviour of B<rbio> and B<wbio>, respectively. -If a BIO 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). - -=head1 RETURN VALUES - -SSL_set_bio() cannot fail. - -=head1 SEE ALSO - -L<SSL_get_rbio(3)|SSL_get_rbio(3)>, -L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_set_connect_state.pod b/openssl/doc/ssl/SSL_set_connect_state.pod deleted file mode 100644 index d88a057..0000000 --- a/openssl/doc/ssl/SSL_set_connect_state.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_connect_state, SSL_get_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)|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)|SSL_CTX_set_ssl_version(3)> or -SSL_set_ssl_method().) - -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)|SSL_connect(3)> or -L<SSL_accept(3)|SSL_accept(3)> routines, the correct handshake -routines are automatically set. When performing a transparent negotiation -using L<SSL_write(3)|SSL_write(3)> or L<SSL_read(3)|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)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, -L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<SSL_write(3)|SSL_write(3)>, L<SSL_read(3)|SSL_read(3)>, -L<SSL_do_handshake(3)|SSL_do_handshake(3)>, -L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_set_fd.pod b/openssl/doc/ssl/SSL_set_fd.pod deleted file mode 100644 index 1480871..0000000 --- a/openssl/doc/ssl/SSL_set_fd.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_fd - 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)|SSL_get_fd(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>, -L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_set_session.pod b/openssl/doc/ssl/SSL_set_session.pod deleted file mode 100644 index 197b521..0000000 --- a/openssl/doc/ssl/SSL_set_session.pod +++ /dev/null @@ -1,57 +0,0 @@ -=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)|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. - -=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)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, -L<SSL_get_session(3)|SSL_get_session(3)>, -L<SSL_session_reused(3)|SSL_session_reused(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_set_shutdown.pod b/openssl/doc/ssl/SSL_set_shutdown.pod deleted file mode 100644 index fe01308..0000000 --- a/openssl/doc/ssl/SSL_set_shutdown.pod +++ /dev/null @@ -1,72 +0,0 @@ -=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)|SSL_clear(3)> or L<SSL_free(3)|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)|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)|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)|ssl(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>, -L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_set_verify_result.pod b/openssl/doc/ssl/SSL_set_verify_result.pod deleted file mode 100644 index 04ab101..0000000 --- a/openssl/doc/ssl/SSL_set_verify_result.pod +++ /dev/null @@ -1,38 +0,0 @@ -=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)|verify(1)>. - -=head1 RETURN VALUES - -SSL_set_verify_result() does not provide a return value. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, -L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, -L<verify(1)|verify(1)> - -=cut diff --git a/openssl/doc/ssl/SSL_shutdown.pod b/openssl/doc/ssl/SSL_shutdown.pod deleted file mode 100644 index efbff5a..0000000 --- a/openssl/doc/ssl/SSL_shutdown.pod +++ /dev/null @@ -1,125 +0,0 @@ -=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)|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)|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). As the shutdown is not -specially handled in the SSLv2 protocol, SSL_shutdown() will succeed on -the first call. - -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)|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)|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)|SSL_get_error(3)> with the return value B<ret> -to find out the reason. - -=back - -=head1 SEE ALSO - -L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, -L<SSL_accept(3)|SSL_accept(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, -L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)>, -L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_state_string.pod b/openssl/doc/ssl/SSL_state_string.pod deleted file mode 100644 index fe25d47..0000000 --- a/openssl/doc/ssl/SSL_state_string.pod +++ /dev/null @@ -1,45 +0,0 @@ -=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)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_want.pod b/openssl/doc/ssl/SSL_want.pod deleted file mode 100644 index c0059c0..0000000 --- a/openssl/doc/ssl/SSL_want.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup - 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); - -=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)|SSL_get_error(3)>. -Unlike L<SSL_get_error(3)|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)|SSL_get_error(3)>. - -The result returned by SSL_want() should always be consistent with -the result of L<SSL_get_error(3)|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)|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)|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)|SSL_get_error(3)> should return -SSL_ERROR_WANT_X509_LOOKUP. - -=back - -SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup() -return 1, when the corresponding condition is true or 0 otherwise. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<err(3)|err(3)>, L<SSL_get_error(3)|SSL_get_error(3)> - -=cut diff --git a/openssl/doc/ssl/SSL_write.pod b/openssl/doc/ssl/SSL_write.pod deleted file mode 100644 index 4c1a7ee..0000000 --- a/openssl/doc/ssl/SSL_write.pod +++ /dev/null @@ -1,106 +0,0 @@ -=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)|SSL_connect(3)> or -L<SSL_accept(3)|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)|SSL_set_connect_state(3)> or SSL_set_accept_state() -before the first call to an L<SSL_read(3)|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)|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)|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)|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. - -SSLv2 (deprecated) does not support a shutdown alert protocol, so it can -only be detected, whether the underlying connection was closed. It cannot -be checked, why the closure happened. - -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)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>, -L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, -L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, -L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> - -=cut diff --git a/openssl/doc/ssl/d2i_SSL_SESSION.pod b/openssl/doc/ssl/d2i_SSL_SESSION.pod deleted file mode 100644 index bce06e2..0000000 --- a/openssl/doc/ssl/d2i_SSL_SESSION.pod +++ /dev/null @@ -1,76 +0,0 @@ -=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 - -d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS -session, stored as binary data at location B<pp> with length B<length>, into -an SSL_SESSION object. - -i2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1 -representation and stores it into the memory location pointed to by B<pp>. -The length of the resulting ASN1 representation is returned. If B<pp> is -the NULL pointer, only the length is calculated and returned. - -=head1 NOTES - -The SSL_SESSION object is built from several malloc()ed parts, it can -therefore not be moved, copied or stored directly. In order to store -session data on disk or into a database, it must be transformed into -a binary ASN1 representation. - -When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically -allocated. The reference count is 1, so that the session must be -explicitly removed using L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, -unless the SSL_SESSION object is completely taken over, when being called -inside the get_session_cb() (see -L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(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). - -When using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be -large enough to hold the binary representation of the session. There is no -known limit on the size of the created ASN1 representation, so the necessary -amount of space should be obtained by first calling i2d_SSL_SESSION() with -B<pp=NULL>, and obtain the size needed, then allocate the memory and -call i2d_SSL_SESSION() again. -Note that this will advance the value contained in B<*pp> so it is necessary -to save a copy of the original allocation. -For example: - int i,j; - char *p, *temp; - i = i2d_SSL_SESSION(sess, NULL); - p = temp = malloc(i); - j = i2d_SSL_SESSION(sess, &temp); - assert(i == j); - assert(p+i == temp); - -=head1 RETURN VALUES - -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)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, -L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> - -=cut diff --git a/openssl/doc/ssl/ssl.pod b/openssl/doc/ssl/ssl.pod deleted file mode 100644 index 70cca17..0000000 --- a/openssl/doc/ssl/ssl.pod +++ /dev/null @@ -1,814 +0,0 @@ - -=pod - -=head1 NAME - -SSL - OpenSSL SSL/TLS library - -=head1 SYNOPSIS - -=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. - -At first the library must be initialized; see -L<SSL_library_init(3)|SSL_library_init(3)>. - -Then an B<SSL_CTX> object is created as a framework to establish -TLS/SSL enabled connections (see L<SSL_CTX_new(3)|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)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or -L<SSL_set_bio(3)|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)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)> -respectively. -L<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used -to read and write data on the TLS/SSL connection. -L<SSL_shutdown(3)|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 (SSLv1, SSLv2 -and 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 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. - -=item B<ssl2.h> - -That's the sub header file dealing with the SSLv2 protocol only. -I<Usually you don't have to include it explicitly because -it's already included by ssl.h>. - -=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<ssl23.h> - -That's the sub header file dealing with the combined use of the SSLv2 and -SSLv3 protocols. -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<SSLv23_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<SSLv23_client_method>(void); - -Constructor for the I<version-flexible> SSL_METHOD structure for -clients. - -=item const SSL_METHOD *B<SSLv23_client_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. - -=item const SSL_METHOD *B<SSLv2_method>(void); - -Constructor for the SSLv2 SSL_METHOD structure for clients, servers -or both. - -=item const SSL_METHOD *B<SSLv2_client_method>(void); - -Constructor for the SSLv2 SSL_METHOD structure for clients. - -=item const SSL_METHOD *B<SSLv2_server_method>(void); - -Constructor for the SSLv2 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<SSL2_TXT_xxx>, I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx> -definitions in the header files. - -=item char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher); - -Returns a string like "C<TLSv1/SSLv3>" or "C<SSLv2>" 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_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, char *CAfile, char *CApath); - -=item long B<SSL_CTX_need_tmp_RSA>(SSL_CTX *ctx); - -=item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth); - -=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 void 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 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); - -=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 void 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 long B<SSL_CTX_set_tmp_rsa>(SSL_CTX *ctx, RSA *rsa); - -=item SSL_CTX_set_tmp_rsa_callback - -C<long B<SSL_CTX_set_tmp_rsa_callback>(SSL_CTX *B<ctx>, RSA *(*B<cb>)(SSL *B<ssl>, int B<export>, int B<keylength>));> - -Sets the callback which will be called when a temporary private key is -required. The B<C<export>> flag will be set if the reason for needing -a temp key is that an export ciphersuite is in use, in which case, -B<C<keylength>> will contain the required keylength in bits. Generate a key of -appropriate size (using ???) and return it. - -=item SSL_set_tmp_rsa_callback - -long B<SSL_set_tmp_rsa_callback>(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength)); - -The same as B<SSL_CTX_set_tmp_rsa_callback>, except it operates on an SSL -session instead of a context. - -=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, 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, 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, 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 void 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 void B<SSL_copy_session_id>(SSL *t, const SSL *f); - -=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); - -=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_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 STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl); - -=item X509 *B<SSL_get_peer_certificate>(const SSL *ssl); - -=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 STACK *B<SSL_load_client_CA_file>(char *file); - -=item void B<SSL_load_error_strings>(void); - -=item SSL *B<SSL_new>(SSL_CTX *ctx); - -=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_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 void 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 int B<SSL_state>(const SSL *ssl); - -=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, 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, 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, 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 SEE ALSO - -L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>, -L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>, -L<SSL_connect(3)|SSL_connect(3)>, -L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>, -L<SSL_COMP_add_compression_method(3)|SSL_COMP_add_compression_method(3)>, -L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, -L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, -L<SSL_CTX_ctrl(3)|SSL_CTX_ctrl(3)>, -L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, -L<SSL_CTX_get_ex_new_index(3)|SSL_CTX_get_ex_new_index(3)>, -L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, -L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> -L<SSL_CTX_new(3)|SSL_CTX_new(3)>, -L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, -L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, -L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, -L<SSL_CTX_sessions(3)|SSL_CTX_sessions(3)>, -L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>, -L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, -L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, -L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, -L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, -L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, -L<SSL_CTX_set_generate_session_id(3)|SSL_CTX_set_generate_session_id(3)>, -L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>, -L<SSL_CTX_set_max_cert_list(3)|SSL_CTX_set_max_cert_list(3)>, -L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, -L<SSL_CTX_set_msg_callback(3)|SSL_CTX_set_msg_callback(3)>, -L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, -L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, -L<SSL_CTX_set_read_ahead(3)|SSL_CTX_set_read_ahead(3)>, -L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, -L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>, -L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, -L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, -L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, -L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, -L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, -L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>, -L<SSL_do_handshake(3)|SSL_do_handshake(3)>, -L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>, -L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, -L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, -L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>, -L<SSL_get_error(3)|SSL_get_error(3)>, -L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, -L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, -L<SSL_get_fd(3)|SSL_get_fd(3)>, -L<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>, -L<SSL_get_rbio(3)|SSL_get_rbio(3)>, -L<SSL_get_session(3)|SSL_get_session(3)>, -L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, -L<SSL_get_version(3)|SSL_get_version(3)>, -L<SSL_library_init(3)|SSL_library_init(3)>, -L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, -L<SSL_new(3)|SSL_new(3)>, -L<SSL_pending(3)|SSL_pending(3)>, -L<SSL_read(3)|SSL_read(3)>, -L<SSL_rstate_string(3)|SSL_rstate_string(3)>, -L<SSL_session_reused(3)|SSL_session_reused(3)>, -L<SSL_set_bio(3)|SSL_set_bio(3)>, -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, -L<SSL_set_fd(3)|SSL_set_fd(3)>, -L<SSL_set_session(3)|SSL_set_session(3)>, -L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, -L<SSL_state_string(3)|SSL_state_string(3)>, -L<SSL_want(3)|SSL_want(3)>, -L<SSL_write(3)|SSL_write(3)>, -L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, -L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>, -L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, -L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, -L<SSL_CTX_set_psk_client_callback(3)|SSL_CTX_set_psk_client_callback(3)>, -L<SSL_CTX_use_psk_identity_hint(3)|SSL_CTX_use_psk_identity_hint(3)>, -L<SSL_get_psk_identity(3)|SSL_get_psk_identity(3)> - -=head1 HISTORY - -The L<ssl(3)|ssl(3)> document appeared in OpenSSL 0.9.2 - -=cut - diff --git a/openssl/doc/ssleay.txt b/openssl/doc/ssleay.txt deleted file mode 100644 index c9b29bd..0000000 --- a/openssl/doc/ssleay.txt +++ /dev/null @@ -1,7030 +0,0 @@ - -Bundle of old SSLeay documentation files [OBSOLETE!] - -*** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! *** - -OBSOLETE means that nothing in this document should be trusted. This -document is provided mostly for historical purposes (it wasn't even up -to date at the time SSLeay 0.8.1 was released) and as inspiration. If -you copy some snippet of code from this document, please _check_ that -it really is correct from all points of view. For example, you can -check with the other documents in this directory tree, or by comparing -with relevant parts of the include files. - -People have done the mistake of trusting what's written here. Please -don't do that. - -*** WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! *** - - -==== readme ======================================================== - -This is the old 0.6.6 docuementation. Most of the cipher stuff is still -relevent but I'm working (very slowly) on new documentation. -The current version can be found online at - -http://www.cryptsoft.com/ssleay/doc - -==== API.doc ======================================================== - -SSL - SSLv2/v3/v23 etc. - -BIO - methods and how they plug together - -MEM - memory allocation callback - -CRYPTO - locking for threads - -EVP - Ciphers/Digests/signatures - -RSA - methods - -X509 - certificate retrieval - -X509 - validation - -X509 - X509v3 extensions - -Objects - adding object identifiers - -ASN.1 - parsing - -PEM - parsing - -==== ssl/readme ===================================================== - -22 Jun 1996 -This file belongs in ../apps, but I'll leave it here because it deals -with SSL :-) It is rather dated but it gives you an idea of how -things work. -=== - -17 Jul 1995 -I have been changing things quite a bit and have not fully updated -this file, so take what you read with a grain of salt -eric -=== -The s_client and s_server programs can be used to test SSL capable -IP/port addresses and the verification of the X509 certificates in use -by these services. I strongly advise having a look at the code to get -an idea of how to use the authentication under SSLeay. Any feedback -on changes and improvements would be greatly accepted. - -This file will probably be gibberish unless you have read -rfc1421, rfc1422, rfc1423 and rfc1424 which describe PEM -authentication. - -A Brief outline (and examples) how to use them to do so. - -NOTE: -The environment variable SSL_CIPER is used to specify the prefered -cipher to use, play around with setting it's value to combinations of -RC4-MD5, EXP-RC4-MD5, CBC-DES-MD5, CBC3-DES-MD5, CFB-DES-NULL -in a : separated list. - -This directory contains 3 X509 certificates which can be used by these programs. -client.pem: a file containing a certificate and private key to be used - by s_client. -server.pem :a file containing a certificate and private key to be used - by s_server. -eay1024.pem:the certificate used to sign client.pem and server.pem. - This would be your CA's certificate. There is also a link - from the file a8556381.0 to eay1024.PEM. The value a8556381 - is returned by 'x509 -hash -noout <eay1024.pem' and is the - value used by X509 verification routines to 'find' this - certificte when search a directory for it. - [the above is not true any more, the CA cert is - ../certs/testca.pem which is signed by ../certs/mincomca.pem] - -When testing the s_server, you may get -bind: Address already in use -errors. These indicate the port is still being held by the unix -kernel and you are going to have to wait for it to let go of it. If -this is the case, remember to use the port commands on the s_server and -s_client to talk on an alternative port. - -===== -s_client. -This program can be used to connect to any IP/hostname:port that is -talking SSL. Once connected, it will attempt to authenticate the -certificate it was passed and if everything works as expected, a 2 -directional channel will be open. Any text typed will be sent to the -other end. type Q<cr> to exit. Flags are as follows. --host arg : Arg is the host or IP address to connect to. --port arg : Arg is the port to connect to (https is 443). --verify arg : Turn on authentication of the server certificate. - : Arg specifies the 'depth', this will covered below. --cert arg : The optional certificate to use. This certificate - : will be returned to the server if the server - : requests it for client authentication. --key arg : The private key that matches the certificate - : specified by the -cert option. If this is not - : specified (but -cert is), the -cert file will be - : searched for the Private key. Both files are - : assumed to be in PEM format. --CApath arg : When to look for certificates when 'verifying' the - : certificate from the server. --CAfile arg : A file containing certificates to be used for - : 'verifying' the server certificate. --reconnect : Once a connection has been made, drop it and - : reconnect with same session-id. This is for testing :-). - -The '-verify n' parameter specifies not only to verify the servers -certificate but to also only take notice of 'n' levels. The best way -to explain is to show via examples. -Given -s_server -cert server.PEM is running. - -s_client - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server - issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify error:num=1:unable to get issuer certificate - verify return:1 - CIPHER is CBC-DES-MD5 -What has happened is that the 'SSLeay demo server' certificate's -issuer ('CA') could not be found but because verify is not on, we -don't care and the connection has been made anyway. It is now 'up' -using CBC-DES-MD5 mode. This is an unauthenticate secure channel. -You may not be talking to the right person but the data going to them -is encrypted. - -s_client -verify 0 - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server - issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify error:num=1:unable to get issuer certificate - verify return:1 - CIPHER is CBC-DES-MD5 -We are 'verifying' but only to depth 0, so since the 'SSLeay demo server' -certificate passed the date and checksum, we are happy to proceed. - -s_client -verify 1 - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server - issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify error:num=1:unable to get issuer certificate - verify return:0 - ERROR - verify error:unable to get issuer certificate -In this case we failed to make the connection because we could not -authenticate the certificate because we could not find the -'CA' certificate. - -s_client -verify 1 -CAfile eay1024.PEM - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server - verify return:1 - depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify return:1 - CIPHER is CBC-DES-MD5 -We loaded the certificates from the file eay1024.PEM. Everything -checked out and so we made the connection. - -s_client -verify 1 -CApath . - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server - verify return:1 - depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify return:1 - CIPHER is CBC-DES-MD5 -We looked in out local directory for issuer certificates and 'found' -a8556381.0 and so everything is ok. - -It is worth noting that 'CA' is a self certified certificate. If you -are passed one of these, it will fail to 'verify' at depth 0 because -we need to lookup the certifier of a certificate from some information -that we trust and keep locally. - -SSL_CIPHER=CBC3-DES-MD5:RC4-MD5 -export SSL_CIPHER -s_client -verify 10 -CApath . -reconnect - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server - verify return:1 - depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify return:1 - drop the connection and reconnect with the same session id - CIPHER is CBC3-DES-MD5 -This has done a full connection and then re-estabished it with the -same session id but a new socket. No RSA stuff occures on the second -connection. Note that we said we would prefer to use CBC3-DES-MD5 -encryption and so, since the server supports it, we are. - -===== -s_server -This program accepts SSL connections on a specified port -Once connected, it will estabish an SSL connection and optionaly -attempt to authenticate the client. A 2 directional channel will be -open. Any text typed will be sent to the other end. Type Q<cr> to exit. -Flags are as follows. --port arg : Arg is the port to listen on. --verify arg : Turn on authentication of the client if they have a - : certificate. Arg specifies the 'depth'. --Verify arg : Turn on authentication of the client. If they don't - : have a valid certificate, drop the connection. --cert arg : The certificate to use. This certificate - : will be passed to the client. If it is not - : specified, it will default to server.PEM --key arg : The private key that matches the certificate - : specified by the -cert option. If this is not - : specified (but -cert is), the -cert file will be - : searched for the Private key. Both files are - : assumed to be in PEM format. Default is server.PEM --CApath arg : When to look for certificates when 'verifying' the - : certificate from the client. --CAfile arg : A file containing certificates to be used for - : 'verifying' the client certificate. - -For the following 'demo' I will specify the s_server command and -the s_client command and then list the output from the s_server. -s_server -s_client - CONNECTED - CIPHER is CBC-DES-MD5 -Everything up and running - -s_server -verify 0 -s_client - CONNECTED - CIPHER is CBC-DES-MD5 -Ok since no certificate was returned and we don't care. - -s_server -verify 0 -./s_client -cert client.PEM - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client - issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify error:num=1:unable to get issuer certificate - verify return:1 - CIPHER is CBC-DES-MD5 -Ok since we were only verifying to level 0 - -s_server -verify 4 -s_client -cert client.PEM - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client - issuer= /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify error:num=1:unable to get issuer certificate - verify return:0 - ERROR - verify error:unable to get issuer certificate -Bad because we could not authenticate the returned certificate. - -s_server -verify 4 -CApath . -s_client -cert client.PEM - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client - verify return:1 - depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify return:1 - CIPHER is CBC-DES-MD5 -Ok because we could authenticate the returned certificate :-). - -s_server -Verify 0 -CApath . -s_client - CONNECTED - ERROR - SSL error:function is:REQUEST_CERTIFICATE - :error is :client end did not return a certificate -Error because no certificate returned. - -s_server -Verify 4 -CApath . -s_client -cert client.PEM - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client - verify return:1 - depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify return:1 - CIPHER is CBC-DES-MD5 -Full authentication of the client. - -So in summary to do full authentication of both ends -s_server -Verify 9 -CApath . -s_client -cert client.PEM -CApath . -verify 9 -From the server side - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo client - verify return:1 - depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify return:1 - CIPHER is CBC-DES-MD5 -From the client side - CONNECTED - depth=0 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=SSLeay demo server - verify return:1 - depth=1 /C=AU/SOP=QLD/O=Mincom Pty. Ltd./OU=CS/CN=CA - verify return:1 - CIPHER is CBC-DES-MD5 - -For general probing of the 'internet https' servers for the -distribution area, run -s_client -host www.netscape.com -port 443 -verify 4 -CApath ../rsa/hash -Then enter -GET / -and you should be talking to the https server on that host. - -www.rsa.com was refusing to respond to connections on 443 when I was -testing. - -have fun :-). - -eric - -==== a_verify.doc ======================================================== - -From eay@mincom.com Fri Oct 4 18:29:06 1996 -Received: by orb.mincom.oz.au id AA29080 - (5.65c/IDA-1.4.4 for eay); Fri, 4 Oct 1996 08:29:07 +1000 -Date: Fri, 4 Oct 1996 08:29:06 +1000 (EST) -From: Eric Young <eay@mincom.oz.au> -X-Sender: eay@orb -To: wplatzer <wplatzer@iaik.tu-graz.ac.at> -Cc: Eric Young <eay@mincom.oz.au>, SSL Mailing List <ssl-users@mincom.com> -Subject: Re: Netscape's Public Key -In-Reply-To: <19961003134837.NTM0049@iaik.tu-graz.ac.at> -Message-Id: <Pine.SOL.3.91.961004081346.8018K-100000@orb> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII -Status: RO -X-Status: - -On Thu, 3 Oct 1996, wplatzer wrote: -> I get Public Key from Netscape (Gold 3.0b4), but cannot do anything -> with it... It looks like (asn1parse): -> -> 0:d=0 hl=3 l=180 cons: SEQUENCE -> 3:d=1 hl=2 l= 96 cons: SEQUENCE -> 5:d=2 hl=2 l= 92 cons: SEQUENCE -> 7:d=3 hl=2 l= 13 cons: SEQUENCE -> 9:d=4 hl=2 l= 9 prim: OBJECT :rsaEncryption -> 20:d=4 hl=2 l= 0 prim: NULL -> 22:d=3 hl=2 l= 75 prim: BIT STRING -> 99:d=2 hl=2 l= 0 prim: IA5STRING : -> 101:d=1 hl=2 l= 13 cons: SEQUENCE -> 103:d=2 hl=2 l= 9 prim: OBJECT :md5withRSAEncryption -> 114:d=2 hl=2 l= 0 prim: NULL -> 116:d=1 hl=2 l= 65 prim: BIT STRING -> -> The first BIT STRING is the public key and the second BIT STRING is -> the signature. -> But a public key consists of the public exponent and the modulus. Are -> both numbers in the first BIT STRING? -> Is there a document simply describing this coding stuff (checking -> signature, get the public key, etc.)? - -Minimal in SSLeay. If you want to see what the modulus and exponent are, -try asn1parse -offset 25 -length 75 <key.pem -asn1parse will currently stuff up on the 'length 75' part (fixed in next -release) but it will print the stuff. If you are after more -documentation on ASN.1, have a look at www.rsa.com and get their PKCS -documents, most of my initial work on SSLeay was done using them. - -As for SSLeay, -util/crypto.num and util/ssl.num are lists of all exported functions in -the library (but not macros :-(. - -The ones for extracting public keys from certificates and certificate -requests are EVP_PKEY * X509_REQ_extract_key(X509_REQ *req); -EVP_PKEY * X509_extract_key(X509 *x509); - -To verify a signature on a signed ASN.1 object -int X509_verify(X509 *a,EVP_PKEY *key); -int X509_REQ_verify(X509_REQ *a,EVP_PKEY *key); -int X509_CRL_verify(X509_CRL *a,EVP_PKEY *key); -int NETSCAPE_SPKI_verify(NETSCAPE_SPKI *a,EVP_PKEY *key); - -I should mention that EVP_PKEY can be used to hold a public or a private key, -since for things like RSA and DSS, a public key is just a subset of what -is stored for the private key. - -To sign any of the above structures - -int X509_sign(X509 *a,EVP_PKEY *key,EVP_MD *md); -int X509_REQ_sign(X509_REQ *a,EVP_PKEY *key,EVP_MD *md); -int X509_CRL_sign(X509_CRL *a,EVP_PKEY *key,EVP_MD *md); -int NETSCAPE_SPKI_sign(NETSCAPE_SPKI *a,EVP_PKEY *key,EVP_MD *md); - -where md is the message digest to sign with. - -There are all defined in x509.h and all the _sign and _verify functions are -actually macros to the ASN1_sign() and ASN1_verify() functions. -These functions will put the correct algorithm identifiers in the correct -places in the structures. - -eric --- -Eric Young | BOOL is tri-state according to Bill Gates. -AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). - -==== x509 ======================================================= - -X509_verify() -X509_sign() - -X509_get_version() -X509_get_serialNumber() -X509_get_issuer() -X509_get_subject() -X509_get_notBefore() -X509_get_notAfter() -X509_get_pubkey() - -X509_set_version() -X509_set_serialNumber() -X509_set_issuer() -X509_set_subject() -X509_set_notBefore() -X509_set_notAfter() -X509_set_pubkey() - -X509_get_extensions() -X509_set_extensions() - -X509_EXTENSIONS_clear() -X509_EXTENSIONS_retrieve() -X509_EXTENSIONS_add() -X509_EXTENSIONS_delete() - -==== x509 attribute ================================================ - -PKCS7 - STACK of X509_ATTRIBUTES - ASN1_OBJECT - STACK of ASN1_TYPE - -So it is - -p7.xa[].obj -p7.xa[].data[] - -get_obj_by_nid(STACK , nid) -get_num_by_nid(STACK , nid) -get_data_by_nid(STACK , nid, index) - -X509_ATTRIBUTE *X509_ATTRIBUTE_new(void ); -void X509_ATTRIBUTE_free(X509_ATTRIBUTE *a); - -X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_NID(X509_ATTRIBUTE **ex, - int nid, STACK *value); - -X509_ATTRIBUTE *X509_ATTRIBUTE_create_by_OBJ(X509_ATTRIBUTE **ex, - int nid, STACK *value); - -int X509_ATTRIBUTE_set_object(X509_ATTRIBUTE *ex,ASN1_OBJECT *obj); -int X509_ATTRIBUTE_add_data(X509_ATTRIBUTE *ex, int index, - ASN1_TYPE *value); - -ASN1_OBJECT * X509_ATTRIBUTE_get_object(X509_ATTRIBUTE *ex); -int X509_ATTRIBUTE_get_num(X509_ATTRIBUTE *ne); -ASN1_TYPE * X509_ATTRIBUTE_get_data(X509_ATTRIBUTE *ne,int index); - -ASN1_TYPE * X509_ATTRIBUTE_get_data_by_NID(X509_ATTRIBUTE *ne, - ASN1_OBJECT *obj); - -X509_ATTRIBUTE *PKCS7_get_s_att_by_NID(PKCS7 *p7,int nid); -X509_ATTRIBUTE *PKCS7_get_u_att_by_NID(PKCS7 *p7,int nid); - -==== x509 v3 ======================================================== - -The 'new' system. - -The X509_EXTENSION_METHOD includes extensions and attributes and/or names. -Basically everthing that can be added to an X509 with an OID identifying it. - -It operates via 2 methods per object id. -int a2i_XXX(X509 *x,char *str,int len); -int i2a_XXX(BIO *bp,X509 *x); - -The a2i_XXX function will add the object with a value converted from the -string into the X509. Len can be -1 in which case the length is calculated -via strlen(str). Applications can always use direct knowledge to load and -unload the relevent objects themselves. - -i2a_XXX will print to the passed BIO, a text representation of the -relevet object. Use a memory BIO if you want it printed to a buffer :-). - -X509_add_by_NID(X509 *x,int nid,char *str,int len); -X509_add_by_OBJ(X509 *x,ASN1_OBJECT *obj,char *str,int len); - -X509_print_by_name(BIO *bp,X509 *x); -X509_print_by_NID(BIO *bp,X509 *x); -X509_print_by_OBJ(BIO *bp,X509 *x); - -==== verify ======================================================== - -X509_verify_cert_chain( - CERT_STORE *cert_store, - STACK /* X509 */ *certs, - int *verify_result, - int (*verify_error_callback)() - char *argument_to_callback, /* SSL */ - -app_verify_callback( - char *app_verify_arg, /* from SSL_CTX */ - STACK /* X509 */ *certs, - int *verify_result, - int (*verify_error_callback)() - SSL *s, - -int X509_verify_cert( - CERT_STORE *cert_store, - X509 *x509, - int *verify_result, - int (*verify_error_callback)(), - char *arg, - -==== apps.doc ======================================================== - -The applications - -Ok, where to begin.... -In the begining, when SSLeay was small (April 1995), there -were but few applications, they did happily cohabit in -the one bin directory. Then over time, they did multiply and grow, -and they started to look like microsoft software; 500k to print 'hello world'. -A new approach was needed. They were coalessed into one 'Monolithic' -application, ssleay. This one program is composed of many programs that -can all be compiled independantly. - -ssleay has 3 modes of operation. -1) If the ssleay binary has the name of one of its component programs, it -executes that program and then exits. This can be achieved by using hard or -symbolic links, or failing that, just renaming the binary. -2) If the first argument to ssleay is the name of one of the component -programs, that program runs that program and then exits. -3) If there are no arguments, ssleay enters a 'command' mode. Each line is -interpreted as a program name plus arguments. After each 'program' is run, -ssleay returns to the comand line. - -dgst - message digests -enc - encryption and base64 encoding - -ans1parse - 'pulls' appart ASN.1 encoded objects like certificates. - -dh - Diffle-Hellman parameter manipulation. -rsa - RSA manipulations. -crl - Certificate revokion list manipulations -x509 - X509 cert fiddles, including signing. -pkcs7 - pkcs7 manipulation, only DER versions right now. - -genrsa - generate an RSA private key. -gendh - Generate a set of Diffle-Hellman parameters. -req - Generate a PKCS#10 object, a certificate request. - -s_client - SSL client program -s_server - SSL server program -s_time - A SSL protocol timing program -s_mult - Another SSL server, but it multiplexes - connections. -s_filter - under development - -errstr - Convert SSLeay error numbers to strings. -ca - Sign certificate requests, and generate - certificate revokion lists -crl2pkcs7 - put a crl and certifcates into a pkcs7 object. -speed - Benchmark the ciphers. -verify - Check certificates -hashdir - under development - -[ there a now a few more options, play with the program to see what they - are ] - -==== asn1.doc ======================================================== - -The ASN.1 Routines. - -ASN.1 is a specification for how to encode structured 'data' in binary form. -The approach I have take to the manipulation of structures and their encoding -into ASN.1 is as follows. - -For each distinct structure there are 4 function of the following form -TYPE *TYPE_new(void); -void TYPE_free(TYPE *); -TYPE *d2i_TYPE(TYPE **a,unsigned char **pp,long length); -long i2d_TYPE(TYPE *a,unsigned char **pp); /* CHECK RETURN VALUE */ - -where TYPE is the type of the 'object'. The TYPE that have these functions -can be in one of 2 forms, either the internal C malloc()ed data structure -or in the DER (a variant of ASN.1 encoding) binary encoding which is just -an array of unsigned bytes. The 'i2d' functions converts from the internal -form to the DER form and the 'd2i' functions convert from the DER form to -the internal form. - -The 'new' function returns a malloc()ed version of the structure with all -substructures either created or left as NULL pointers. For 'optional' -fields, they are normally left as NULL to indicate no value. For variable -size sub structures (often 'SET OF' or 'SEQUENCE OF' in ASN.1 syntax) the -STACK data type is used to hold the values. Have a read of stack.doc -and have a look at the relevant header files to see what I mean. If there -is an error while malloc()ing the structure, NULL is returned. - -The 'free' function will free() all the sub components of a particular -structure. If any of those sub components have been 'removed', replace -them with NULL pointers, the 'free' functions are tolerant of NULL fields. - -The 'd2i' function copies a binary representation into a C structure. It -operates as follows. 'a' is a pointer to a pointer to -the structure to populate, 'pp' is a pointer to a pointer to where the DER -byte string is located and 'length' is the length of the '*pp' data. -If there are no errors, a pointer to the populated structure is returned. -If there is an error, NULL is returned. Errors can occur because of -malloc() failures but normally they will be due to syntax errors in the DER -encoded data being parsed. It is also an error if there was an -attempt to read more that 'length' bytes from '*p'. If -everything works correctly, the value in '*p' is updated -to point at the location just beyond where the DER -structure was read from. In this way, chained calls to 'd2i' type -functions can be made, with the pointer into the 'data' array being -'walked' along the input byte array. -Depending on the value passed for 'a', different things will be done. If -'a' is NULL, a new structure will be malloc()ed and returned. If '*a' is -NULL, a new structure will be malloc()ed and put into '*a' and returned. -If '*a' is not NULL, the structure in '*a' will be populated, or in the -case of an error, free()ed and then returned. -Having these semantics means that a structure -can call a 'd2i' function to populate a field and if the field is currently -NULL, the structure will be created. - -The 'i2d' function type is used to copy a C structure to a byte array. -The parameter 'a' is the structure to convert and '*p' is where to put it. -As for the 'd2i' type structure, 'p' is updated to point after the last -byte written. If p is NULL, no data is written. The function also returns -the number of bytes written. Where this becomes useful is that if the -function is called with a NULL 'p' value, the length is returned. This can -then be used to malloc() an array of bytes and then the same function can -be recalled passing the malloced array to be written to. e.g. - -int len; -unsigned char *bytes,*p; -len=i2d_X509(x,NULL); /* get the size of the ASN1 encoding of 'x' */ -if ((bytes=(unsigned char *)malloc(len)) == NULL) - goto err; -p=bytes; -i2d_X509(x,&p); - -Please note that a new variable, 'p' was passed to i2d_X509. After the -call to i2d_X509 p has been incremented by len bytes. - -Now the reason for this functional organisation is that it allows nested -structures to be built up by calling these functions as required. There -are various macros used to help write the general 'i2d', 'd2i', 'new' and -'free' functions. They are discussed in another file and would only be -used by some-one wanting to add new structures to the library. As you -might be able to guess, the process of writing ASN.1 files can be a bit CPU -expensive for complex structures. I'm willing to live with this since the -simpler library code make my life easier and hopefully most programs using -these routines will have their execution profiles dominated by cipher or -message digest routines. -What follows is a list of 'TYPE' values and the corresponding ASN.1 -structure and where it is used. - -TYPE ASN.1 -ASN1_INTEGER INTEGER -ASN1_BIT_STRING BIT STRING -ASN1_OCTET_STRING OCTET STRING -ASN1_OBJECT OBJECT IDENTIFIER -ASN1_PRINTABLESTRING PrintableString -ASN1_T61STRING T61String -ASN1_IA5STRING IA5String -ASN1_UTCTIME UTCTime -ASN1_TYPE Any of the above mentioned types plus SEQUENCE and SET - -Most of the above mentioned types are actualled stored in the -ASN1_BIT_STRING type and macros are used to differentiate between them. -The 3 types used are - -typedef struct asn1_object_st - { - /* both null if a dynamic ASN1_OBJECT, one is - * defined if a 'static' ASN1_OBJECT */ - char *sn,*ln; - int nid; - int length; - unsigned char *data; - } ASN1_OBJECT; -This is used to store ASN1 OBJECTS. Read 'objects.doc' for details ono -routines to manipulate this structure. 'sn' and 'ln' are used to hold text -strings that represent the object (short name and long or lower case name). -These are used by the 'OBJ' library. 'nid' is a number used by the OBJ -library to uniquely identify objects. The ASN1 routines will populate the -'length' and 'data' fields which will contain the bit string representing -the object. - -typedef struct asn1_bit_string_st - { - int length; - int type; - unsigned char *data; - } ASN1_BIT_STRING; -This structure is used to hold all the other base ASN1 types except for -ASN1_UTCTIME (which is really just a 'char *'). Length is the number of -bytes held in data and type is the ASN1 type of the object (there is a list -in asn1.h). - -typedef struct asn1_type_st - { - int type; - union { - char *ptr; - ASN1_INTEGER * integer; - ASN1_BIT_STRING * bit_string; - ASN1_OCTET_STRING * octet_string; - ASN1_OBJECT * object; - ASN1_PRINTABLESTRING * printablestring; - ASN1_T61STRING * t61string; - ASN1_IA5STRING * ia5string; - ASN1_UTCTIME * utctime; - ASN1_BIT_STRING * set; - ASN1_BIT_STRING * sequence; - } value; - } ASN1_TYPE; -This structure is used in a few places when 'any' type of object can be -expected. - -X509 Certificate -X509_CINF CertificateInfo -X509_ALGOR AlgorithmIdentifier -X509_NAME Name -X509_NAME_ENTRY A single sub component of the name. -X509_VAL Validity -X509_PUBKEY SubjectPublicKeyInfo -The above mentioned types are declared in x509.h. They are all quite -straight forward except for the X509_NAME/X509_NAME_ENTRY pair. -A X509_NAME is a STACK (see stack.doc) of X509_NAME_ENTRY's. -typedef struct X509_name_entry_st - { - ASN1_OBJECT *object; - ASN1_BIT_STRING *value; - int set; - int size; /* temp variable */ - } X509_NAME_ENTRY; -The size is a temporary variable used by i2d_NAME and set is the set number -for the particular NAME_ENTRY. A X509_NAME is encoded as a sequence of -sequence of sets. Normally each set contains only a single item. -Sometimes it contains more. Normally throughout this library there will be -only one item per set. The set field contains the 'set' that this entry is -a member of. So if you have just created a X509_NAME structure and -populated it with X509_NAME_ENTRYs, you should then traverse the X509_NAME -(which is just a STACK) and set the 'set/' field to incrementing numbers. -For more details on why this is done, read the ASN.1 spec for Distinguished -Names. - -X509_REQ CertificateRequest -X509_REQ_INFO CertificateRequestInfo -These are used to hold certificate requests. - -X509_CRL CertificateRevocationList -These are used to hold a certificate revocation list - -RSAPrivateKey PrivateKeyInfo -RSAPublicKey PublicKeyInfo -Both these 'function groups' operate on 'RSA' structures (see rsa.doc). -The difference is that the RSAPublicKey operations only manipulate the m -and e fields in the RSA structure. - -DSAPrivateKey DSS private key -DSAPublicKey DSS public key -Both these 'function groups' operate on 'DSS' structures (see dsa.doc). -The difference is that the RSAPublicKey operations only manipulate the -XXX fields in the DSA structure. - -DHparams DHParameter -This is used to hold the p and g value for The Diffie-Hellman operation. -The function deal with the 'DH' strucure (see dh.doc). - -Now all of these function types can be used with several other functions to give -quite useful set of general manipulation routines. Normally one would -not uses these functions directly but use them via macros. - -char *ASN1_dup(int (*i2d)(),char *(*d2i)(),char *x); -'x' is the input structure case to a 'char *', 'i2d' is the 'i2d_TYPE' -function for the type that 'x' is and d2i is the 'd2i_TYPE' function for the -type that 'x' is. As is obvious from the parameters, this function -duplicates the strucutre by transforming it into the DER form and then -re-loading it into a new strucutre and returning the new strucutre. This -is obviously a bit cpu intensive but when faced with a complex dynamic -structure this is the simplest programming approach. There are macros for -duplicating the major data types but is simple to add extras. - -char *ASN1_d2i_fp(char *(*new)(),char *(*d2i)(),FILE *fp,unsigned char **x); -'x' is a pointer to a pointer of the 'desired type'. new and d2i are the -corresponding 'TYPE_new' and 'd2i_TYPE' functions for the type and 'fp' is -an open file pointer to read from. This function reads from 'fp' as much -data as it can and then uses 'd2i' to parse the bytes to load and return -the parsed strucutre in 'x' (if it was non-NULL) and to actually return the -strucutre. The behavior of 'x' is as per all the other d2i functions. - -char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x); -The 'BIO' is the new IO type being used in SSLeay (see bio.doc). This -function is the same as ASN1_d2i_fp() except for the BIO argument. -ASN1_d2i_fp() actually calls this function. - -int ASN1_i2d_fp(int (*i2d)(),FILE *out,unsigned char *x); -'x' is converted to bytes by 'i2d' and then written to 'out'. ASN1_i2d_fp -and ASN1_d2i_fp are not really symetric since ASN1_i2d_fp will read all -available data from the file pointer before parsing a single item while -ASN1_i2d_fp can be used to write a sequence of data objects. To read a -series of objects from a file I would sugest loading the file into a buffer -and calling the relevent 'd2i' functions. - -char *ASN1_d2i_bio(char *(*new)(),char *(*d2i)(),BIO *fp,unsigned char **x); -This function is the same as ASN1_i2d_fp() except for the BIO argument. -ASN1_i2d_fp() actually calls this function. - -char * PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)()); -This function will read the next PEM encoded (base64) object of the same -type as 'x' (loaded by the d2i function). 'name' is the name that is in -the '-----BEGIN name-----' that designates the start of that object type. -If the data is encrypted, 'cb' will be called to prompt for a password. If -it is NULL a default function will be used to prompt from the password. -'x' is delt with as per the standard 'd2i' function interface. This -function can be used to read a series of objects from a file. While any -data type can be encrypted (see PEM_ASN1_write) only RSA private keys tend -to be encrypted. - -char * PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *fp, - char **x,int (*cb)()); -Same as PEM_ASN1_read() except using a BIO. This is called by -PEM_ASN1_read(). - -int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x,EVP_CIPHER *enc, - unsigned char *kstr,int klen,int (*callback)()); - -int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *fp, - char *x,EVP_CIPHER *enc,unsigned char *kstr,int klen, - int (*callback)()); - -int ASN1_sign(int (*i2d)(), X509_ALGOR *algor1, X509_ALGOR *algor2, - ASN1_BIT_STRING *signature, char *data, RSA *rsa, EVP_MD *type); -int ASN1_verify(int (*i2d)(), X509_ALGOR *algor1, - ASN1_BIT_STRING *signature,char *data, RSA *rsa); - -int ASN1_BIT_STRING_cmp(ASN1_BIT_STRING *a, ASN1_BIT_STRING *b); -ASN1_BIT_STRING *ASN1_BIT_STRING_type_new(int type ); - -int ASN1_UTCTIME_check(ASN1_UTCTIME *a); -void ASN1_UTCTIME_print(BIO *fp,ASN1_UTCTIME *a); -ASN1_UTCTIME *ASN1_UTCTIME_dup(ASN1_UTCTIME *a); - -ASN1_BIT_STRING *d2i_asn1_print_type(ASN1_BIT_STRING **a,unsigned char **pp, - long length,int type); - -int i2d_ASN1_SET(STACK *a, unsigned char **pp, - int (*func)(), int ex_tag, int ex_class); -STACK * d2i_ASN1_SET(STACK **a, unsigned char **pp, long length, - char *(*func)(), int ex_tag, int ex_class); - -int i2a_ASN1_OBJECT(BIO *bp,ASN1_OBJECT *object); -int i2a_ASN1_INTEGER(BIO *bp, ASN1_INTEGER *a); -int a2i_ASN1_INTEGER(BIO *bp,ASN1_INTEGER *bs,char *buf,int size); - -int ASN1_INTEGER_set(ASN1_INTEGER *a, long v); -long ASN1_INTEGER_get(ASN1_INTEGER *a); -ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai); -BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn); - -/* given a string, return the correct type. Max is the maximum number - * of bytes to parse. It stops parsing when 'max' bytes have been - * processed or a '\0' is hit */ -int ASN1_PRINTABLE_type(unsigned char *s,int max); - -void ASN1_parse(BIO *fp,unsigned char *pp,long len); - -int i2d_ASN1_bytes(ASN1_BIT_STRING *a, unsigned char **pp, int tag, int class); -ASN1_BIT_STRING *d2i_ASN1_bytes(ASN1_OCTET_STRING **a, unsigned char **pp, - long length, int Ptag, int Pclass); - -/* PARSING */ -int asn1_Finish(ASN1_CTX *c); - -/* SPECIALS */ -int ASN1_get_object(unsigned char **pp, long *plength, int *ptag, - int *pclass, long omax); -int ASN1_check_infinite_end(unsigned char **p,long len); -void ASN1_put_object(unsigned char **pp, int constructed, int length, - int tag, int class); -int ASN1_object_size(int constructed, int length, int tag); - -X509 * X509_get_cert(CERTIFICATE_CTX *ctx,X509_NAME * name,X509 *tmp_x509); -int X509_add_cert(CERTIFICATE_CTX *ctx,X509 *); - -char * X509_cert_verify_error_string(int n); -int X509_add_cert_file(CERTIFICATE_CTX *c,char *file, int type); -char * X509_gmtime (char *s, long adj); -int X509_add_cert_dir (CERTIFICATE_CTX *c,char *dir, int type); -int X509_load_verify_locations (CERTIFICATE_CTX *ctx, - char *file_env, char *dir_env); -int X509_set_default_verify_paths(CERTIFICATE_CTX *cts); -X509 * X509_new_D2i_X509(int len, unsigned char *p); -char * X509_get_default_cert_area(void ); -char * X509_get_default_cert_dir(void ); -char * X509_get_default_cert_file(void ); -char * X509_get_default_cert_dir_env(void ); -char * X509_get_default_cert_file_env(void ); -char * X509_get_default_private_dir(void ); -X509_REQ *X509_X509_TO_req(X509 *x, RSA *rsa); -int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)()); - -CERTIFICATE_CTX *CERTIFICATE_CTX_new(); -void CERTIFICATE_CTX_free(CERTIFICATE_CTX *c); - -void X509_NAME_print(BIO *fp, X509_NAME *name, int obase); -int X509_print_fp(FILE *fp,X509 *x); -int X509_print(BIO *fp,X509 *x); - -X509_INFO * X509_INFO_new(void); -void X509_INFO_free(X509_INFO *a); - -char * X509_NAME_oneline(X509_NAME *a); - -#define X509_verify(x,rsa) -#define X509_REQ_verify(x,rsa) -#define X509_CRL_verify(x,rsa) - -#define X509_sign(x,rsa,md) -#define X509_REQ_sign(x,rsa,md) -#define X509_CRL_sign(x,rsa,md) - -#define X509_dup(x509) -#define d2i_X509_fp(fp,x509) -#define i2d_X509_fp(fp,x509) -#define d2i_X509_bio(bp,x509) -#define i2d_X509_bio(bp,x509) - -#define X509_CRL_dup(crl) -#define d2i_X509_CRL_fp(fp,crl) -#define i2d_X509_CRL_fp(fp,crl) -#define d2i_X509_CRL_bio(bp,crl) -#define i2d_X509_CRL_bio(bp,crl) - -#define X509_REQ_dup(req) -#define d2i_X509_REQ_fp(fp,req) -#define i2d_X509_REQ_fp(fp,req) -#define d2i_X509_REQ_bio(bp,req) -#define i2d_X509_REQ_bio(bp,req) - -#define RSAPrivateKey_dup(rsa) -#define d2i_RSAPrivateKey_fp(fp,rsa) -#define i2d_RSAPrivateKey_fp(fp,rsa) -#define d2i_RSAPrivateKey_bio(bp,rsa) -#define i2d_RSAPrivateKey_bio(bp,rsa) - -#define X509_NAME_dup(xn) -#define X509_NAME_ENTRY_dup(ne) - -void X509_REQ_print_fp(FILE *fp,X509_REQ *req); -void X509_REQ_print(BIO *fp,X509_REQ *req); - -RSA *X509_REQ_extract_key(X509_REQ *req); -RSA *X509_extract_key(X509 *x509); - -int X509_issuer_and_serial_cmp(X509 *a, X509 *b); -unsigned long X509_issuer_and_serial_hash(X509 *a); - -X509_NAME * X509_get_issuer_name(X509 *a); -int X509_issuer_name_cmp(X509 *a, X509 *b); -unsigned long X509_issuer_name_hash(X509 *a); - -X509_NAME * X509_get_subject_name(X509 *a); -int X509_subject_name_cmp(X509 *a,X509 *b); -unsigned long X509_subject_name_hash(X509 *x); - -int X509_NAME_cmp (X509_NAME *a, X509_NAME *b); -unsigned long X509_NAME_hash(X509_NAME *x); - - -==== bio.doc ======================================================== - -BIO Routines - -This documentation is rather sparse, you are probably best -off looking at the code for specific details. - -The BIO library is a IO abstraction that was originally -inspired by the need to have callbacks to perform IO to FILE -pointers when using Windows 3.1 DLLs. There are two types -of BIO; a source/sink type and a filter type. -The source/sink methods are as follows: -- BIO_s_mem() memory buffer - a read/write byte array that - grows until memory runs out :-). -- BIO_s_file() FILE pointer - A wrapper around the normal - 'FILE *' commands, good for use with stdin/stdout. -- BIO_s_fd() File descriptor - A wrapper around file - descriptors, often used with pipes. -- BIO_s_socket() Socket - Used around sockets. It is - mostly in the Microsoft world that sockets are different - from file descriptors and there are all those ugly winsock - commands. -- BIO_s_null() Null - read nothing and write nothing.; a - useful endpoint for filter type BIO's specifically things - like the message digest BIO. - -The filter types are -- BIO_f_buffer() IO buffering - does output buffering into - larger chunks and performs input buffering to allow gets() - type functions. -- BIO_f_md() Message digest - a transparent filter that can - be asked to return a message digest for the data that has - passed through it. -- BIO_f_cipher() Encrypt or decrypt all data passing - through the filter. -- BIO_f_base64() Base64 decode on read and encode on write. -- BIO_f_ssl() A filter that performs SSL encryption on the - data sent through it. - -Base BIO functions. -The BIO library has a set of base functions that are -implemented for each particular type. Filter BIOs will -normally call the equivalent function on the source/sink BIO -that they are layered on top of after they have performed -some modification to the data stream. Multiple filter BIOs -can be 'push' into a stack of modifers, so to read from a -file, unbase64 it, then decrypt it, a BIO_f_cipher, -BIO_f_base64 and a BIO_s_file would probably be used. If a -sha-1 and md5 message digest needed to be generated, a stack -two BIO_f_md() BIOs and a BIO_s_null() BIO could be used. -The base functions are -- BIO *BIO_new(BIO_METHOD *type); Create a new BIO of type 'type'. -- int BIO_free(BIO *a); Free a BIO structure. Depending on - the configuration, this will free the underlying data - object for a source/sink BIO. -- int BIO_read(BIO *b, char *data, int len); Read upto 'len' - bytes into 'data'. -- int BIO_gets(BIO *bp,char *buf, int size); Depending on - the BIO, this can either be a 'get special' or a get one - line of data, as per fgets(); -- int BIO_write(BIO *b, char *data, int len); Write 'len' - bytes from 'data' to the 'b' BIO. -- int BIO_puts(BIO *bp,char *buf); Either a 'put special' or - a write null terminated string as per fputs(). -- long BIO_ctrl(BIO *bp,int cmd,long larg,char *parg); A - control function which is used to manipulate the BIO - structure and modify it's state and or report on it. This - function is just about never used directly, rather it - should be used in conjunction with BIO_METHOD specific - macros. -- BIO *BIO_push(BIO *new_top, BIO *old); new_top is apped to the - top of the 'old' BIO list. new_top should be a filter BIO. - All writes will go through 'new_top' first and last on read. - 'old' is returned. -- BIO *BIO_pop(BIO *bio); the new topmost BIO is returned, NULL if - there are no more. - -If a particular low level BIO method is not supported -(normally BIO_gets()), -2 will be returned if that method is -called. Otherwise the IO methods (read, write, gets, puts) -will return the number of bytes read or written, and 0 or -1 -for error (or end of input). For the -1 case, -BIO_should_retry(bio) can be called to determine if it was a -genuine error or a temporary problem. -2 will also be -returned if the BIO has not been initalised yet, in all -cases, the correct error codes are set (accessible via the -ERR library). - - -The following functions are convenience functions: -- int BIO_printf(BIO *bio, char * format, ..); printf but - to a BIO handle. -- long BIO_ctrl_int(BIO *bp,int cmd,long larg,int iarg); a - convenience function to allow a different argument types - to be passed to BIO_ctrl(). -- int BIO_dump(BIO *b,char *bytes,int len); output 'len' - bytes from 'bytes' in a hex dump debug format. -- long BIO_debug_callback(BIO *bio, int cmd, char *argp, int - argi, long argl, long ret) - a default debug BIO callback, - this is mentioned below. To use this one normally has to - use the BIO_set_callback_arg() function to assign an - output BIO for the callback to use. -- BIO *BIO_find_type(BIO *bio,int type); when there is a 'stack' - of BIOs, this function scan the list and returns the first - that is of type 'type', as listed in buffer.h under BIO_TYPE_XXX. -- void BIO_free_all(BIO *bio); Free the bio and all other BIOs - in the list. It walks the bio->next_bio list. - - - -Extra commands are normally implemented as macros calling BIO_ctrl(). -- BIO_number_read(BIO *bio) - the number of bytes processed - by BIO_read(bio,.). -- BIO_number_written(BIO *bio) - the number of bytes written - by BIO_write(bio,.). -- BIO_reset(BIO *bio) - 'reset' the BIO. -- BIO_eof(BIO *bio) - non zero if we are at the current end - of input. -- BIO_set_close(BIO *bio, int close_flag) - set the close flag. -- BIO_get_close(BIO *bio) - return the close flag. - BIO_pending(BIO *bio) - return the number of bytes waiting - to be read (normally buffered internally). -- BIO_flush(BIO *bio) - output any data waiting to be output. -- BIO_should_retry(BIO *io) - after a BIO_read/BIO_write - operation returns 0 or -1, a call to this function will - return non zero if you should retry the call later (this - is for non-blocking IO). -- BIO_should_read(BIO *io) - we should retry when data can - be read. -- BIO_should_write(BIO *io) - we should retry when data can - be written. -- BIO_method_name(BIO *io) - return a string for the method name. -- BIO_method_type(BIO *io) - return the unique ID of the BIO method. -- BIO_set_callback(BIO *io, long (*callback)(BIO *io, int - cmd, char *argp, int argi, long argl, long ret); - sets - the debug callback. -- BIO_get_callback(BIO *io) - return the assigned function - as mentioned above. -- BIO_set_callback_arg(BIO *io, char *arg) - assign some - data against the BIO. This is normally used by the debug - callback but could in reality be used for anything. To - get an idea of how all this works, have a look at the code - in the default debug callback mentioned above. The - callback can modify the return values. - -Details of the BIO_METHOD structure. -typedef struct bio_method_st - { - int type; - char *name; - int (*bwrite)(); - int (*bread)(); - int (*bputs)(); - int (*bgets)(); - long (*ctrl)(); - int (*create)(); - int (*destroy)(); - } BIO_METHOD; - -The 'type' is the numeric type of the BIO, these are listed in buffer.h; -'Name' is a textual representation of the BIO 'type'. -The 7 function pointers point to the respective function -methods, some of which can be NULL if not implemented. -The BIO structure -typedef struct bio_st - { - BIO_METHOD *method; - long (*callback)(BIO * bio, int mode, char *argp, int - argi, long argl, long ret); - char *cb_arg; /* first argument for the callback */ - int init; - int shutdown; - int flags; /* extra storage */ - int num; - char *ptr; - struct bio_st *next_bio; /* used by filter BIOs */ - int references; - unsigned long num_read; - unsigned long num_write; - } BIO; - -- 'Method' is the BIO method. -- 'callback', when configured, is called before and after - each BIO method is called for that particular BIO. This - is intended primarily for debugging and of informational feedback. -- 'init' is 0 when the BIO can be used for operation. - Often, after a BIO is created, a number of operations may - need to be performed before it is available for use. An - example is for BIO_s_sock(). A socket needs to be - assigned to the BIO before it can be used. -- 'shutdown', this flag indicates if the underlying - communication primitive being used should be closed/freed - when the BIO is closed. -- 'flags' is used to hold extra state. It is primarily used - to hold information about why a non-blocking operation - failed and to record startup protocol information for the - SSL BIO. -- 'num' and 'ptr' are used to hold instance specific state - like file descriptors or local data structures. -- 'next_bio' is used by filter BIOs to hold the pointer of the - next BIO in the chain. written data is sent to this BIO and - data read is taken from it. -- 'references' is used to indicate the number of pointers to - this structure. This needs to be '1' before a call to - BIO_free() is made if the BIO_free() function is to - actually free() the structure, otherwise the reference - count is just decreased. The actual BIO subsystem does - not really use this functionality but it is useful when - used in more advanced applicaion. -- num_read and num_write are the total number of bytes - read/written via the 'read()' and 'write()' methods. - -BIO_ctrl operations. -The following is the list of standard commands passed as the -second parameter to BIO_ctrl() and should be supported by -all BIO as best as possible. Some are optional, some are -manditory, in any case, where is makes sense, a filter BIO -should pass such requests to underlying BIO's. -- BIO_CTRL_RESET - Reset the BIO back to an initial state. -- BIO_CTRL_EOF - return 0 if we are not at the end of input, - non 0 if we are. -- BIO_CTRL_INFO - BIO specific special command, normal - information return. -- BIO_CTRL_SET - set IO specific parameter. -- BIO_CTRL_GET - get IO specific parameter. -- BIO_CTRL_GET_CLOSE - Get the close on BIO_free() flag, one - of BIO_CLOSE or BIO_NOCLOSE. -- BIO_CTRL_SET_CLOSE - Set the close on BIO_free() flag. -- BIO_CTRL_PENDING - Return the number of bytes available - for instant reading -- BIO_CTRL_FLUSH - Output pending data, return number of bytes output. -- BIO_CTRL_SHOULD_RETRY - After an IO error (-1 returned) - should we 'retry' when IO is possible on the underlying IO object. -- BIO_CTRL_RETRY_TYPE - What kind of IO are we waiting on. - -The following command is a special BIO_s_file() specific option. -- BIO_CTRL_SET_FILENAME - specify a file to open for IO. - -The BIO_CTRL_RETRY_TYPE needs a little more explanation. -When performing non-blocking IO, or say reading on a memory -BIO, when no data is present (or cannot be written), -BIO_read() and/or BIO_write() will return -1. -BIO_should_retry(bio) will return true if this is due to an -IO condition rather than an actual error. In the case of -BIO_s_mem(), a read when there is no data will return -1 and -a should retry when there is more 'read' data. -The retry type is deduced from 2 macros -BIO_should_read(bio) and BIO_should_write(bio). -Now while it may appear obvious that a BIO_read() failure -should indicate that a retry should be performed when more -read data is available, this is often not true when using -things like an SSL BIO. During the SSL protocol startup -multiple reads and writes are performed, triggered by any -SSL_read or SSL_write. -So to write code that will transparently handle either a -socket or SSL BIO, - i=BIO_read(bio,..) - if (I == -1) - { - if (BIO_should_retry(bio)) - { - if (BIO_should_read(bio)) - { - /* call us again when BIO can be read */ - } - if (BIO_should_write(bio)) - { - /* call us again when BIO can be written */ - } - } - } - -At this point in time only read and write conditions can be -used but in the future I can see the situation for other -conditions, specifically with SSL there could be a condition -of a X509 certificate lookup taking place and so the non- -blocking BIO_read would require a retry when the certificate -lookup subsystem has finished it's lookup. This is all -makes more sense and is easy to use in a event loop type -setup. -When using the SSL BIO, either SSL_read() or SSL_write()s -can be called during the protocol startup and things will -still work correctly. -The nice aspect of the use of the BIO_should_retry() macro -is that all the errno codes that indicate a non-fatal error -are encapsulated in one place. The Windows specific error -codes and WSAGetLastError() calls are also hidden from the -application. - -Notes on each BIO method. -Normally buffer.h is just required but depending on the -BIO_METHOD, ssl.h or evp.h will also be required. - -BIO_METHOD *BIO_s_mem(void); -- BIO_set_mem_buf(BIO *bio, BUF_MEM *bm, int close_flag) - - set the underlying BUF_MEM structure for the BIO to use. -- BIO_get_mem_ptr(BIO *bio, char **pp) - if pp is not NULL, - set it to point to the memory array and return the number - of bytes available. -A read/write BIO. Any data written is appended to the -memory array and any read is read from the front. This BIO -can be used for read/write at the same time. BIO_gets() is -supported in the fgets() sense. -BIO_CTRL_INFO can be used to retrieve pointers to the memory -buffer and it's length. - -BIO_METHOD *BIO_s_file(void); -- BIO_set_fp(BIO *bio, FILE *fp, int close_flag) - set 'FILE *' to use. -- BIO_get_fp(BIO *bio, FILE **fp) - get the 'FILE *' in use. -- BIO_read_filename(BIO *bio, char *name) - read from file. -- BIO_write_filename(BIO *bio, char *name) - write to file. -- BIO_append_filename(BIO *bio, char *name) - append to file. -This BIO sits over the normal system fread()/fgets() type -functions. Gets() is supported. This BIO in theory could be -used for read and write but it is best to think of each BIO -of this type as either a read or a write BIO, not both. - -BIO_METHOD *BIO_s_socket(void); -BIO_METHOD *BIO_s_fd(void); -- BIO_sock_should_retry(int i) - the underlying function - used to determine if a call should be retried; the - argument is the '0' or '-1' returned by the previous BIO - operation. -- BIO_fd_should_retry(int i) - same as the -- BIO_sock_should_retry() except that it is different internally. -- BIO_set_fd(BIO *bio, int fd, int close_flag) - set the - file descriptor to use -- BIO_get_fd(BIO *bio, int *fd) - get the file descriptor. -These two methods are very similar. Gets() is not -supported, if you want this functionality, put a -BIO_f_buffer() onto it. This BIO is bi-directional if the -underlying file descriptor is. This is normally the case -for sockets but not the case for stdio descriptors. - -BIO_METHOD *BIO_s_null(void); -Read and write as much data as you like, it all disappears -into this BIO. - -BIO_METHOD *BIO_f_buffer(void); -- BIO_get_buffer_num_lines(BIO *bio) - return the number of - complete lines in the buffer. -- BIO_set_buffer_size(BIO *bio, long size) - set the size of - the buffers. -This type performs input and output buffering. It performs -both at the same time. The size of the buffer can be set -via the set buffer size option. Data buffered for output is -only written when the buffer fills. - -BIO_METHOD *BIO_f_ssl(void); -- BIO_set_ssl(BIO *bio, SSL *ssl, int close_flag) - the SSL - structure to use. -- BIO_get_ssl(BIO *bio, SSL **ssl) - get the SSL structure - in use. -The SSL bio is a little different from normal BIOs because -the underlying SSL structure is a little different. A SSL -structure performs IO via a read and write BIO. These can -be different and are normally set via the -SSL_set_rbio()/SSL_set_wbio() calls. The SSL_set_fd() calls -are just wrappers that create socket BIOs and then call -SSL_set_bio() where the read and write BIOs are the same. -The BIO_push() operation makes the SSLs IO BIOs the same, so -make sure the BIO pushed is capable of two directional -traffic. If it is not, you will have to install the BIOs -via the more conventional SSL_set_bio() call. BIO_pop() will retrieve -the 'SSL read' BIO. - -BIO_METHOD *BIO_f_md(void); -- BIO_set_md(BIO *bio, EVP_MD *md) - set the message digest - to use. -- BIO_get_md(BIO *bio, EVP_MD **mdp) - return the digest - method in use in mdp, return 0 if not set yet. -- BIO_reset() reinitializes the digest (EVP_DigestInit()) - and passes the reset to the underlying BIOs. -All data read or written via BIO_read() or BIO_write() to -this BIO will be added to the calculated digest. This -implies that this BIO is only one directional. If read and -write operations are performed, two separate BIO_f_md() BIOs -are reuqired to generate digests on both the input and the -output. BIO_gets(BIO *bio, char *md, int size) will place the -generated digest into 'md' and return the number of bytes. -The EVP_MAX_MD_SIZE should probably be used to size the 'md' -array. Reading the digest will also reset it. - -BIO_METHOD *BIO_f_cipher(void); -- BIO_reset() reinitializes the cipher. -- BIO_flush() should be called when the last bytes have been - output to flush the final block of block ciphers. -- BIO_get_cipher_status(BIO *b), when called after the last - read from a cipher BIO, returns non-zero if the data - decrypted correctly, otherwise, 0. -- BIO_set_cipher(BIO *b, EVP_CIPHER *c, unsigned char *key, - unsigned char *iv, int encrypt) This function is used to - setup a cipher BIO. The length of key and iv are - specified by the choice of EVP_CIPHER. Encrypt is 1 to - encrypt and 0 to decrypt. - -BIO_METHOD *BIO_f_base64(void); -- BIO_flush() should be called when the last bytes have been output. -This BIO base64 encodes when writing and base64 decodes when -reading. It will scan the input until a suitable begin line -is found. After reading data, BIO_reset() will reset the -BIO to start scanning again. Do not mix reading and writing -on the same base64 BIO. It is meant as a single stream BIO. - -Directions type -both BIO_s_mem() -one/both BIO_s_file() -both BIO_s_fd() -both BIO_s_socket() -both BIO_s_null() -both BIO_f_buffer() -one BIO_f_md() -one BIO_f_cipher() -one BIO_f_base64() -both BIO_f_ssl() - -It is easy to mix one and two directional BIOs, all one has -to do is to keep two separate BIO pointers for reading and -writing and be careful about usage of underlying BIOs. The -SSL bio by it's very nature has to be two directional but -the BIO_push() command will push the one BIO into the SSL -BIO for both reading and writing. - -The best example program to look at is apps/enc.c and/or perhaps apps/dgst.c. - - -==== blowfish.doc ======================================================== - -The Blowfish library. - -Blowfish is a block cipher that operates on 64bit (8 byte) quantities. It -uses variable size key, but 128bit (16 byte) key would normally be considered -good. It can be used in all the modes that DES can be used. This -library implements the ecb, cbc, cfb64, ofb64 modes. - -Blowfish is quite a bit faster that DES, and much faster than IDEA or -RC2. It is one of the faster block ciphers. - -For all calls that have an 'input' and 'output' variables, they can be the -same. - -This library requires the inclusion of 'blowfish.h'. - -All of the encryption functions take what is called an BF_KEY as an -argument. An BF_KEY is an expanded form of the Blowfish key. -For all modes of the Blowfish algorithm, the BF_KEY used for -decryption is the same one that was used for encryption. - -The define BF_ENCRYPT is passed to specify encryption for the functions -that require an encryption/decryption flag. BF_DECRYPT is passed to -specify decryption. - -Please note that any of the encryption modes specified in my DES library -could be used with Blowfish. I have only implemented ecb, cbc, cfb64 and -ofb64 for the following reasons. -- ecb is the basic Blowfish encryption. -- cbc is the normal 'chaining' form for block ciphers. -- cfb64 can be used to encrypt single characters, therefore input and output - do not need to be a multiple of 8. -- ofb64 is similar to cfb64 but is more like a stream cipher, not as - secure (not cipher feedback) but it does not have an encrypt/decrypt mode. -- If you want triple Blowfish, thats 384 bits of key and you must be totally - obsessed with security. Still, if you want it, it is simple enough to - copy the function from the DES library and change the des_encrypt to - BF_encrypt; an exercise left for the paranoid reader :-). - -The functions are as follows: - -void BF_set_key( -BF_KEY *ks; -int len; -unsigned char *key; - BF_set_key converts an 'len' byte key into a BF_KEY. - A 'ks' is an expanded form of the 'key' which is used to - perform actual encryption. It can be regenerated from the Blowfish key - so it only needs to be kept when encryption or decryption is about - to occur. Don't save or pass around BF_KEY's since they - are CPU architecture dependent, 'key's are not. Blowfish is an - interesting cipher in that it can be used with a variable length - key. 'len' is the length of 'key' to be used as the key. - A 'len' of 16 is recomended by me, but blowfish can use upto - 72 bytes. As a warning, blowfish has a very very slow set_key - function, it actually runs BF_encrypt 521 times. - -void BF_encrypt(unsigned long *data, BF_KEY *key); -void BF_decrypt(unsigned long *data, BF_KEY *key); - These are the Blowfish encryption function that gets called by just - about every other Blowfish routine in the library. You should not - use this function except to implement 'modes' of Blowfish. - I say this because the - functions that call this routine do the conversion from 'char *' to - long, and this needs to be done to make sure 'non-aligned' memory - access do not occur. - Data is a pointer to 2 unsigned long's and key is the - BF_KEY to use. - -void BF_ecb_encrypt( -unsigned char *in, -unsigned char *out, -BF_KEY *key, -int encrypt); - This is the basic Electronic Code Book form of Blowfish (in DES this - mode is called Electronic Code Book so I'm going to use the term - for blowfish as well. - Input is encrypted into output using the key represented by - key. Depending on the encrypt, encryption or - decryption occurs. Input is 8 bytes long and output is 8 bytes. - -void BF_cbc_encrypt( -unsigned char *in, -unsigned char *out, -long length, -BF_KEY *ks, -unsigned char *ivec, -int encrypt); - This routine implements Blowfish in Cipher Block Chaining mode. - Input, which should be a multiple of 8 bytes is encrypted - (or decrypted) to output which will also be a multiple of 8 bytes. - The number of bytes is in length (and from what I've said above, - should be a multiple of 8). If length is not a multiple of 8, bad - things will probably happen. ivec is the initialisation vector. - This function updates iv after each call so that it can be passed to - the next call to BF_cbc_encrypt(). - -void BF_cfb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -BF_KEY *schedule, -unsigned char *ivec, -int *num, -int encrypt); - This is one of the more useful functions in this Blowfish library, it - implements CFB mode of Blowfish with 64bit feedback. - This allows you to encrypt an arbitrary number of bytes, - you do not require 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. - 'Encrypt' is used to indicate encryption or decryption. - CFB64 mode operates by using the cipher to generate a stream - of bytes which is used to encrypt the plain text. - The cipher text is then encrypted to generate the next 64 bits to - be xored (incrementally) with the next 64 bits of plain - text. As can be seen from this, to encrypt or decrypt, - the same 'cipher stream' needs to be generated but the way the next - block of data is gathered for encryption is different for - encryption and decryption. - -void BF_ofb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -BF_KEY *schedule, -unsigned char *ivec, -int *num); - This functions implements OFB mode of Blowfish with 64bit feedback. - This allows you to encrypt an arbitrary number of bytes, - you do not require 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. - This is in effect a stream cipher, there is no encryption or - decryption mode. - -For reading passwords, I suggest using des_read_pw_string() from my DES library. -To generate a password from a text string, I suggest using MD5 (or MD2) to -produce a 16 byte message digest that can then be passed directly to -BF_set_key(). - -===== -For more information about the specific Blowfish modes in this library -(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the -documentation on my DES library. What is said about DES is directly -applicable for Blowfish. - - -==== bn.doc ======================================================== - -The Big Number library. - -#include "bn.h" when using this library. - -This big number library was written for use in implementing the RSA and DH -public key encryption algorithms. As such, features such as negative -numbers have not been extensively tested but they should work as expected. -This library uses dynamic memory allocation for storing its data structures -and so there are no limit on the size of the numbers manipulated by these -routines but there is always the requirement to check return codes from -functions just in case a memory allocation error has occurred. - -The basic object in this library is a BIGNUM. It is used to hold a single -large integer. This type should be considered opaque and fields should not -be modified or accessed directly. -typedef struct bignum_st - { - int top; /* Index of last used d. */ - BN_ULONG *d; /* Pointer to an array of 'BITS2' bit chunks. */ - int max; /* Size of the d array. */ - int neg; - } BIGNUM; -The big number is stored in a malloced array of BN_ULONG's. A BN_ULONG can -be either 16, 32 or 64 bits in size, depending on the 'number of bits' -specified in bn.h. -The 'd' field is this array. 'max' is the size of the 'd' array that has -been allocated. 'top' is the 'last' entry being used, so for a value of 4, -bn.d[0]=4 and bn.top=1. 'neg' is 1 if the number is negative. -When a BIGNUM is '0', the 'd' field can be NULL and top == 0. - -Various routines in this library require the use of 'temporary' BIGNUM -variables during their execution. Due to the use of dynamic memory -allocation to create BIGNUMs being rather expensive when used in -conjunction with repeated subroutine calls, the BN_CTX structure is -used. This structure contains BN_CTX BIGNUMs. BN_CTX -is the maximum number of temporary BIGNUMs any publicly exported -function will use. - -#define BN_CTX 12 -typedef struct bignum_ctx - { - int tos; /* top of stack */ - BIGNUM *bn[BN_CTX]; /* The variables */ - } BN_CTX; - -The functions that follow have been grouped according to function. Most -arithmetic functions return a result in the first argument, sometimes this -first argument can also be an input parameter, sometimes it cannot. These -restrictions are documented. - -extern BIGNUM *BN_value_one; -There is one variable defined by this library, a BIGNUM which contains the -number 1. This variable is useful for use in comparisons and assignment. - -Get Size functions. - -int BN_num_bits(BIGNUM *a); - This function returns the size of 'a' in bits. - -int BN_num_bytes(BIGNUM *a); - This function (macro) returns the size of 'a' in bytes. - For conversion of BIGNUMs to byte streams, this is the number of - bytes the output string will occupy. If the output byte - format specifies that the 'top' bit indicates if the number is - signed, so an extra '0' byte is required if the top bit on a - positive number is being written, it is upto the application to - make this adjustment. Like I said at the start, I don't - really support negative numbers :-). - -Creation/Destruction routines. - -BIGNUM *BN_new(); - Return a new BIGNUM object. The number initially has a value of 0. If - there is an error, NULL is returned. - -void BN_free(BIGNUM *a); - Free()s a BIGNUM. - -void BN_clear(BIGNUM *a); - Sets 'a' to a value of 0 and also zeros all unused allocated - memory. This function is used to clear a variable of 'sensitive' - data that was held in it. - -void BN_clear_free(BIGNUM *a); - This function zeros the memory used by 'a' and then free()'s it. - This function should be used to BN_free() BIGNUMS that have held - sensitive numeric values like RSA private key values. Both this - function and BN_clear tend to only be used by RSA and DH routines. - -BN_CTX *BN_CTX_new(void); - Returns a new BN_CTX. NULL on error. - -void BN_CTX_free(BN_CTX *c); - Free a BN_CTX structure. The BIGNUMs in 'c' are BN_clear_free()ed. - -BIGNUM *bn_expand(BIGNUM *b, int bits); - This is an internal function that should not normally be used. It - ensures that 'b' has enough room for a 'bits' bit number. It is - mostly used by the various BIGNUM routines. If there is an error, - NULL is returned. if not, 'b' is returned. - -BIGNUM *BN_copy(BIGNUM *to, BIGNUM *from); - The 'from' is copied into 'to'. NULL is returned if there is an - error, otherwise 'to' is returned. - -BIGNUM *BN_dup(BIGNUM *a); - A new BIGNUM is created and returned containing the value of 'a'. - NULL is returned on error. - -Comparison and Test Functions. - -int BN_is_zero(BIGNUM *a) - Return 1 if 'a' is zero, else 0. - -int BN_is_one(a) - Return 1 is 'a' is one, else 0. - -int BN_is_word(a,w) - Return 1 if 'a' == w, else 0. 'w' is a BN_ULONG. - -int BN_cmp(BIGNUM *a, BIGNUM *b); - Return -1 if 'a' is less than 'b', 0 if 'a' and 'b' are the same - and 1 is 'a' is greater than 'b'. This is a signed comparison. - -int BN_ucmp(BIGNUM *a, BIGNUM *b); - This function is the same as BN_cmp except that the comparison - ignores the sign of the numbers. - -Arithmetic Functions -For all of these functions, 0 is returned if there is an error and 1 is -returned for success. The return value should always be checked. eg. -if (!BN_add(r,a,b)) goto err; -Unless explicitly mentioned, the 'return' value can be one of the -'parameters' to the function. - -int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b); - Add 'a' and 'b' and return the result in 'r'. This is r=a+b. - -int BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b); - Subtract 'a' from 'b' and put the result in 'r'. This is r=a-b. - -int BN_lshift(BIGNUM *r, BIGNUM *a, int n); - Shift 'a' left by 'n' bits. This is r=a*(2^n). - -int BN_lshift1(BIGNUM *r, BIGNUM *a); - Shift 'a' left by 1 bit. This form is more efficient than - BN_lshift(r,a,1). This is r=a*2. - -int BN_rshift(BIGNUM *r, BIGNUM *a, int n); - Shift 'a' right by 'n' bits. This is r=int(a/(2^n)). - -int BN_rshift1(BIGNUM *r, BIGNUM *a); - Shift 'a' right by 1 bit. This form is more efficient than - BN_rshift(r,a,1). This is r=int(a/2). - -int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b); - Multiply a by b and return the result in 'r'. 'r' must not be - either 'a' or 'b'. It has to be a different BIGNUM. - This is r=a*b. - -int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); - Multiply a by a and return the result in 'r'. 'r' must not be - 'a'. This function is alot faster than BN_mul(r,a,a). This is r=a*a. - -int BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); - Divide 'm' by 'd' and return the result in 'dv' and the remainder - in 'rem'. Either of 'dv' or 'rem' can be NULL in which case that - value is not returned. 'ctx' needs to be passed as a source of - temporary BIGNUM variables. - This is dv=int(m/d), rem=m%d. - -int BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx); - Find the remainder of 'm' divided by 'd' and return it in 'rem'. - 'ctx' holds the temporary BIGNUMs required by this function. - This function is more efficient than BN_div(NULL,rem,m,d,ctx); - This is rem=m%d. - -int BN_mod_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BIGNUM *m,BN_CTX *ctx); - Multiply 'a' by 'b' and return the remainder when divided by 'm'. - 'ctx' holds the temporary BIGNUMs required by this function. - This is r=(a*b)%m. - -int BN_mod_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx); - Raise 'a' to the 'p' power and return the remainder when divided by - 'm'. 'ctx' holds the temporary BIGNUMs required by this function. - This is r=(a^p)%m. - -int BN_reciprocal(BIGNUM *r, BIGNUM *m, BN_CTX *ctx); - Return the reciprocal of 'm'. 'ctx' holds the temporary variables - required. This function returns -1 on error, otherwise it returns - the number of bits 'r' is shifted left to make 'r' into an integer. - This number of bits shifted is required in BN_mod_mul_reciprocal(). - This is r=(1/m)<<(BN_num_bits(m)+1). - -int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y, BIGNUM *m, - BIGNUM *i, int nb, BN_CTX *ctx); - This function is used to perform an efficient BN_mod_mul() - operation. If one is going to repeatedly perform BN_mod_mul() with - the same modulus is worth calculating the reciprocal of the modulus - and then using this function. This operation uses the fact that - a/b == a*r where r is the reciprocal of b. On modern computers - multiplication is very fast and big number division is very slow. - 'x' is multiplied by 'y' and then divided by 'm' and the remainder - is returned. 'i' is the reciprocal of 'm' and 'nb' is the number - of bits as returned from BN_reciprocal(). Normal usage is as follows. - bn=BN_reciprocal(i,m); - for (...) - { BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); } - This is r=(x*y)%m. Internally it is approximately - r=(x*y)-m*(x*y/m) or r=(x*y)-m*((x*y*i) >> bn) - This function is used in BN_mod_exp() and BN_is_prime(). - -Assignment Operations - -int BN_one(BIGNUM *a) - Set 'a' to hold the value one. - This is a=1. - -int BN_zero(BIGNUM *a) - Set 'a' to hold the value zero. - This is a=0. - -int BN_set_word(BIGNUM *a, unsigned long w); - Set 'a' to hold the value of 'w'. 'w' is an unsigned long. - This is a=w. - -unsigned long BN_get_word(BIGNUM *a); - Returns 'a' in an unsigned long. Not remarkably, often 'a' will - be bigger than a word, in which case 0xffffffffL is returned. - -Word Operations -These functions are much more efficient that the normal bignum arithmetic -operations. - -BN_ULONG BN_mod_word(BIGNUM *a, unsigned long w); - Return the remainder of 'a' divided by 'w'. - This is return(a%w). - -int BN_add_word(BIGNUM *a, unsigned long w); - Add 'w' to 'a'. This function does not take the sign of 'a' into - account. This is a+=w; - -Bit operations. - -int BN_is_bit_set(BIGNUM *a, int n); - This function return 1 if bit 'n' is set in 'a' else 0. - -int BN_set_bit(BIGNUM *a, int n); - This function sets bit 'n' to 1 in 'a'. - This is a&= ~(1<<n); - -int BN_clear_bit(BIGNUM *a, int n); - This function sets bit 'n' to zero in 'a'. Return 0 if less - than 'n' bits in 'a' else 1. This is a&= ~(1<<n); - -int BN_mask_bits(BIGNUM *a, int n); - Truncate 'a' to n bits long. This is a&= ~((~0)<<n) - -Format conversion routines. - -BIGNUM *BN_bin2bn(unsigned char *s, int len,BIGNUM *ret); - This function converts 'len' bytes in 's' into a BIGNUM which - is put in 'ret'. If ret is NULL, a new BIGNUM is created. - Either this new BIGNUM or ret is returned. The number is - assumed to be in bigendian form in 's'. By this I mean that - to 'ret' is created as follows for 'len' == 5. - ret = s[0]*2^32 + s[1]*2^24 + s[2]*2^16 + s[3]*2^8 + s[4]; - This function cannot be used to convert negative numbers. It - is always assumed the number is positive. The application - needs to diddle the 'neg' field of th BIGNUM its self. - The better solution would be to save the numbers in ASN.1 format - since this is a defined standard for storing big numbers. - Look at the functions - - ASN1_INTEGER *BN_to_ASN1_INTEGER(BIGNUM *bn, ASN1_INTEGER *ai); - BIGNUM *ASN1_INTEGER_to_BN(ASN1_INTEGER *ai,BIGNUM *bn); - int i2d_ASN1_INTEGER(ASN1_INTEGER *a,unsigned char **pp); - ASN1_INTEGER *d2i_ASN1_INTEGER(ASN1_INTEGER **a,unsigned char **pp, - long length; - -int BN_bn2bin(BIGNUM *a, unsigned char *to); - This function converts 'a' to a byte string which is put into - 'to'. The representation is big-endian in that the most - significant byte of 'a' is put into to[0]. This function - returns the number of bytes used to hold 'a'. BN_num_bytes(a) - would return the same value and can be used to determine how - large 'to' needs to be. If the number is negative, this - information is lost. Since this library was written to - manipulate large positive integers, the inability to save and - restore them is not considered to be a problem by me :-). - As for BN_bin2bn(), look at the ASN.1 integer encoding funtions - for SSLeay. They use BN_bin2bn() and BN_bn2bin() internally. - -char *BN_bn2ascii(BIGNUM *a); - This function returns a malloc()ed string that contains the - ascii hexadecimal encoding of 'a'. The number is in bigendian - format with a '-' in front if the number is negative. - -int BN_ascii2bn(BIGNUM **bn, char *a); - The inverse of BN_bn2ascii. The function returns the number of - characters from 'a' were processed in generating a the bignum. - error is inticated by 0 being returned. The number is a - hex digit string, optionally with a leading '-'. If *bn - is null, a BIGNUM is created and returned via that variable. - -int BN_print_fp(FILE *fp, BIGNUM *a); - 'a' is printed to file pointer 'fp'. It is in the same format - that is output from BN_bn2ascii(). 0 is returned on error, - 1 if things are ok. - -int BN_print(BIO *bp, BIGNUM *a); - Same as BN_print except that the output is done to the SSLeay libraries - BIO routines. BN_print_fp() actually calls this function. - -Miscellaneous Routines. - -int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); - This function returns in 'rnd' a random BIGNUM that is bits - long. If bottom is 1, the number returned is odd. If top is set, - the top 2 bits of the number are set. This is useful because if - this is set, 2 'n; bit numbers multiplied together will return a 2n - bit number. If top was not set, they could produce a 2n-1 bit - number. - -BIGNUM *BN_mod_inverse(BIGNUM *a, BIGNUM *n,BN_CTX *ctx); - This function create a new BIGNUM and returns it. This number - is the inverse mod 'n' of 'a'. By this it is meant that the - returned value 'r' satisfies (a*r)%n == 1. This function is - used in the generation of RSA keys. 'ctx', as per usual, - is used to hold temporary variables that are required by the - function. NULL is returned on error. - -int BN_gcd(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_CTX *ctx); - 'r' has the greatest common divisor of 'a' and 'b'. 'ctx' is - used for temporary variables and 0 is returned on error. - -int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(),BN_CTX *ctx, - char *cb_arg); - This function is used to check if a BIGNUM ('p') is prime. - It performs this test by using the Miller-Rabin randomised - primality test. This is a probalistic test that requires a - number of rounds to ensure the number is prime to a high - degree of probability. Since this can take quite some time, a - callback function can be passed and it will be called each - time 'p' passes a round of the prime testing. 'callback' will - be called as follows, callback(1,n,cb_arg) where n is the number of - the round, just passed. As per usual 'ctx' contains temporary - variables used. If ctx is NULL, it does not matter, a local version - will be malloced. This parameter is present to save some mallocing - inside the function but probably could be removed. - 0 is returned on error. - 'ncheck' is the number of Miller-Rabin tests to run. It is - suggested to use the value 'BN_prime_checks' by default. - -BIGNUM *BN_generate_prime( -int bits, -int strong, -BIGNUM *a, -BIGNUM *rems, -void (*callback)()); -char *cb_arg - This function is used to generate prime numbers. It returns a - new BIGNUM that has a high probability of being a prime. - 'bits' is the number of bits that - are to be in the prime. If 'strong' is true, the returned prime - will also be a strong prime ((p-1)/2 is also prime). - While searching for the prime ('p'), we - can add the requirement that the prime fill the following - condition p%a == rem. This can be used to help search for - primes with specific features, which is required when looking - for primes suitable for use with certain 'g' values in the - Diffie-Hellman key exchange algorithm. If 'a' is NULL, - this condition is not checked. If rem is NULL, rem is assumed - to be 1. Since this search for a prime - can take quite some time, if callback is not NULL, it is called - in the following situations. - We have a suspected prime (from a quick sieve), - callback(0,sus_prime++,cb_arg). Each item to be passed to BN_is_prime(). - callback(1,round++,cb_arg). Each successful 'round' in BN_is_prime(). - callback(2,round,cb_arg). For each successful BN_is_prime() test. - -Hints ------ - -DSA wants 64*32 to use word mont mul, but RSA wants to use full. - -==== callback.doc ======================================================== - -Callback functions used in SSLeay. - --------------------------- -The BIO library. - -Each BIO structure can have a callback defined against it. This callback is -called 2 times for each BIO 'function'. It is passed 6 parameters. -BIO_debug_callback() is an example callback which is defined in -crypto/buffer/bio_cb.c and is used in apps/dgst.c This is intended mostly -for debuging or to notify the application of IO. - -long BIO_debug_callback(BIO *bio,int cmd,char *argp,int argi,long argl, - long ret); -bio is the BIO being called, cmd is the type of BIO function being called. -Look at the BIO_CB_* defines in buffer.h. Argp and argi are the arguments -passed to BIO_read(), BIO_write, BIO_gets(), BIO_puts(). In the case of -BIO_ctrl(), argl is also defined. The first time the callback is called, -before the underlying function has been executed, 0 is passed as 'ret', and -if the return code from the callback is not > 0, the call is aborted -and the returned <= 0 value is returned. -The second time the callback is called, the 'cmd' value also has -BIO_CB_RETURN logically 'or'ed with it. The 'ret' value is the value returned -from the actuall function call and whatever the callback returns is returned -from the BIO function. - -BIO_set_callback(b,cb) can be used to set the callback function -(b is a BIO), and BIO_set_callback_arg(b,arg) can be used to -set the cb_arg argument in the BIO strucutre. This field is only intended -to be used by application, primarily in the callback function since it is -accessable since the BIO is passed. - --------------------------- -The PEM library. - -The pem library only really uses one type of callback, -static int def_callback(char *buf, int num, int verify); -which is used to return a password string if required. -'buf' is the buffer to put the string in. 'num' is the size of 'buf' -and 'verify' is used to indicate that the password should be checked. -This last flag is mostly used when reading a password for encryption. - -For all of these functions, a NULL callback will call the above mentioned -default callback. This default function does not work under Windows 3.1. -For other machines, it will use an application defined prompt string -(EVP_set_pw_prompt(), which defines a library wide prompt string) -if defined, otherwise it will use it's own PEM password prompt. -It will then call EVP_read_pw_string() to get a password from the console. -If your application wishes to use nice fancy windows to retrieve passwords, -replace this function. The callback should return the number of bytes read -into 'buf'. If the number of bytes <= 0, it is considered an error. - -Functions that take this callback are listed below. For the 'read' type -functions, the callback will only be required if the PEM data is encrypted. - -For the Write functions, normally a password can be passed in 'kstr', of -'klen' bytes which will be used if the 'enc' cipher is not NULL. If -'kstr' is NULL, the callback will be used to retrieve a password. - -int PEM_do_header (EVP_CIPHER_INFO *cipher, unsigned char *data,long *len, - int (*callback)()); -char *PEM_ASN1_read_bio(char *(*d2i)(),char *name,BIO *bp,char **x,int (*cb)()); -char *PEM_ASN1_read(char *(*d2i)(),char *name,FILE *fp,char **x,int (*cb)()); -int PEM_ASN1_write_bio(int (*i2d)(),char *name,BIO *bp,char *x, - EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)()); -int PEM_ASN1_write(int (*i2d)(),char *name,FILE *fp,char *x, - EVP_CIPHER *enc,unsigned char *kstr,int klen,int (*callback)()); -STACK *PEM_X509_INFO_read(FILE *fp, STACK *sk, int (*cb)()); -STACK *PEM_X509_INFO_read_bio(BIO *fp, STACK *sk, int (*cb)()); - -#define PEM_write_RSAPrivateKey(fp,x,enc,kstr,klen,cb) -#define PEM_write_DSAPrivateKey(fp,x,enc,kstr,klen,cb) -#define PEM_write_bio_RSAPrivateKey(bp,x,enc,kstr,klen,cb) -#define PEM_write_bio_DSAPrivateKey(bp,x,enc,kstr,klen,cb) -#define PEM_read_SSL_SESSION(fp,x,cb) -#define PEM_read_X509(fp,x,cb) -#define PEM_read_X509_REQ(fp,x,cb) -#define PEM_read_X509_CRL(fp,x,cb) -#define PEM_read_RSAPrivateKey(fp,x,cb) -#define PEM_read_DSAPrivateKey(fp,x,cb) -#define PEM_read_PrivateKey(fp,x,cb) -#define PEM_read_PKCS7(fp,x,cb) -#define PEM_read_DHparams(fp,x,cb) -#define PEM_read_bio_SSL_SESSION(bp,x,cb) -#define PEM_read_bio_X509(bp,x,cb) -#define PEM_read_bio_X509_REQ(bp,x,cb) -#define PEM_read_bio_X509_CRL(bp,x,cb) -#define PEM_read_bio_RSAPrivateKey(bp,x,cb) -#define PEM_read_bio_DSAPrivateKey(bp,x,cb) -#define PEM_read_bio_PrivateKey(bp,x,cb) -#define PEM_read_bio_PKCS7(bp,x,cb) -#define PEM_read_bio_DHparams(bp,x,cb) -int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); -RSA *d2i_Netscape_RSA(RSA **a, unsigned char **pp, long length, int (*cb)()); - -Now you will notice that macros like -#define PEM_write_X509(fp,x) \ - PEM_ASN1_write((int (*)())i2d_X509,PEM_STRING_X509,fp, \ - (char *)x, NULL,NULL,0,NULL) -Don't do encryption normally. If you want to PEM encrypt your X509 structure, -either just call PEM_ASN1_write directly or just define your own -macro variant. As you can see, this macro just sets all encryption related -parameters to NULL. - - --------------------------- -The SSL library. - -#define SSL_set_info_callback(ssl,cb) -#define SSL_CTX_set_info_callback(ctx,cb) -void callback(SSL *ssl,int location,int ret) -This callback is called each time around the SSL_connect()/SSL_accept() -state machine. So it will be called each time the SSL protocol progresses. -It is mostly present for use when debugging. When SSL_connect() or -SSL_accept() return, the location flag is SSL_CB_ACCEPT_EXIT or -SSL_CB_CONNECT_EXIT and 'ret' is the value about to be returned. -Have a look at the SSL_CB_* defines in ssl.h. If an info callback is defined -against the SSL_CTX, it is called unless there is one set against the SSL. -Have a look at -void client_info_callback() in apps/s_client() for an example. - -Certificate verification. -void SSL_set_verify(SSL *s, int mode, int (*callback) ()); -void SSL_CTX_set_verify(SSL_CTX *ctx,int mode,int (*callback)()); -This callback is used to help verify client and server X509 certificates. -It is actually passed to X509_cert_verify(), along with the SSL structure -so you have to read about X509_cert_verify() :-). The SSL_CTX version is used -if the SSL version is not defined. X509_cert_verify() is the function used -by the SSL part of the library to verify certificates. This function is -nearly always defined by the application. - -void SSL_CTX_set_cert_verify_cb(SSL_CTX *ctx, int (*cb)(),char *arg); -int callback(char *arg,SSL *s,X509 *xs,STACK *cert_chain); -This call is used to replace the SSLeay certificate verification code. -The 'arg' is kept in the SSL_CTX and is passed to the callback. -If the callback returns 0, the certificate is rejected, otherwise it -is accepted. The callback is replacing the X509_cert_verify() call. -This feature is not often used, but if you wished to implement -some totally different certificate authentication system, this 'hook' is -vital. - -SSLeay keeps a cache of session-ids against each SSL_CTX. These callbacks can -be used to notify the application when a SSL_SESSION is added to the cache -or to retrieve a SSL_SESSION that is not in the cache from the application. -#define SSL_CTX_sess_set_get_cb(ctx,cb) -SSL_SESSION *callback(SSL *s,char *session_id,int session_id_len,int *copy); -If defined, this callback is called to return the SESSION_ID for the -session-id in 'session_id', of 'session_id_len' bytes. 'copy' is set to 1 -if the server is to 'take a copy' of the SSL_SESSION structure. It is 0 -if the SSL_SESSION is being 'passed in' so the SSLeay library is now -responsible for 'free()ing' the structure. Basically it is used to indicate -if the reference count on the SSL_SESSION structure needs to be incremented. - -#define SSL_CTX_sess_set_new_cb(ctx,cb) -int callback(SSL *s, SSL_SESSION *sess); -When a new connection is established, if the SSL_SESSION is going to be added -to the cache, this callback is called. Return 1 if a 'copy' is required, -otherwise, return 0. This return value just causes the reference count -to be incremented (on return of a 1), this means the application does -not need to worry about incrementing the refernece count (and the -locking that implies in a multi-threaded application). - -void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx,int (*cb)()); -This sets the SSL password reading function. -It is mostly used for windowing applications -and used by PEM_read_bio_X509() and PEM_read_bio_RSAPrivateKey() -calls inside the SSL library. The only reason this is present is because the -calls to PEM_* functions is hidden in the SSLeay library so you have to -pass in the callback some how. - -#define SSL_CTX_set_client_cert_cb(ctx,cb) -int callback(SSL *s,X509 **x509, EVP_PKEY **pkey); -Called when a client certificate is requested but there is not one set -against the SSL_CTX or the SSL. If the callback returns 1, x509 and -pkey need to point to valid data. The library will free these when -required so if the application wants to keep these around, increment -their reference counts. If 0 is returned, no client cert is -available. If -1 is returned, it is assumed that the callback needs -to be called again at a later point in time. SSL_connect will return --1 and SSL_want_x509_lookup(ssl) returns true. Remember that -application data can be attached to an SSL structure via the -SSL_set_app_data(SSL *ssl,char *data) call. - --------------------------- -The X509 library. - -int X509_cert_verify(CERTIFICATE_CTX *ctx,X509 *xs, int (*cb)(), - int *error,char *arg,STACK *cert_chain); -int verify_callback(int ok,X509 *xs,X509 *xi,int depth,int error,char *arg, - STACK *cert_chain); - -X509_cert_verify() is used to authenticate X509 certificates. The 'ctx' holds -the details of the various caches and files used to locate certificates. -'xs' is the certificate to verify and 'cb' is the application callback (more -detail later). 'error' will be set to the error code and 'arg' is passed -to the 'cb' callback. Look at the VERIFY_* defines in crypto/x509/x509.h - -When ever X509_cert_verify() makes a 'negative' decision about a -certitificate, the callback is called. If everything checks out, the -callback is called with 'VERIFY_OK' or 'VERIFY_ROOT_OK' (for a self -signed cert that is not the passed certificate). - -The callback is passed the X509_cert_verify opinion of the certificate -in 'ok', the certificate in 'xs', the issuer certificate in 'xi', -the 'depth' of the certificate in the verification 'chain', the -VERIFY_* code in 'error' and the argument passed to X509_cert_verify() -in 'arg'. cert_chain is a list of extra certs to use if they are not -in the cache. - -The callback can be used to look at the error reason, and then return 0 -for an 'error' or '1' for ok. This will override the X509_cert_verify() -opinion of the certificates validity. Processing will continue depending on -the return value. If one just wishes to use the callback for informational -reason, just return the 'ok' parameter. - --------------------------- -The BN and DH library. - -BIGNUM *BN_generate_prime(int bits,int strong,BIGNUM *add, - BIGNUM *rem,void (*callback)(int,int)); -int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int), - -Read doc/bn.doc for the description of these 2. - -DH *DH_generate_parameters(int prime_len,int generator, - void (*callback)(int,int)); -Read doc/bn.doc for the description of the callback, since it is just passed -to BN_generate_prime(), except that it is also called as -callback(3,0) by this function. - --------------------------- -The CRYPTO library. - -void CRYPTO_set_locking_callback(void (*func)(int mode,int type,char *file, - int line)); -void CRYPTO_set_add_lock_callback(int (*func)(int *num,int mount, - int type,char *file, int line)); -void CRYPTO_set_id_callback(unsigned long (*func)(void)); - -Read threads.doc for info on these ones. - - -==== cipher.doc ======================================================== - -The Cipher subroutines. - -These routines require "evp.h" to be included. - -These functions are a higher level interface to the various cipher -routines found in this library. As such, they allow the same code to be -used to encrypt and decrypt via different ciphers with only a change -in an initial parameter. These routines also provide buffering for block -ciphers. - -These routines all take a pointer to the following structure to specify -which cipher to use. If you wish to use a new cipher with these routines, -you would probably be best off looking an how an existing cipher is -implemented and copying it. At this point in time, I'm not going to go -into many details. This structure should be considered opaque - -typedef struct pem_cipher_st - { - int type; - int block_size; - int key_len; - int iv_len; - void (*enc_init)(); /* init for encryption */ - void (*dec_init)(); /* init for decryption */ - void (*do_cipher)(); /* encrypt data */ - } EVP_CIPHER; - -The type field is the object NID of the cipher type -(read the section on Objects for an explanation of what a NID is). -The cipher block_size is how many bytes need to be passed -to the cipher at a time. Key_len is the -length of the key the cipher requires and iv_len is the length of the -initialisation vector required. enc_init is the function -called to initialise the ciphers context for encryption and dec_init is the -function to initialise for decryption (they need to be different, especially -for the IDEA cipher). - -One reason for specifying the Cipher via a pointer to a structure -is that if you only use des-cbc, only the des-cbc routines will -be included when you link the program. If you passed an integer -that specified which cipher to use, the routine that mapped that -integer to a set of cipher functions would cause all the ciphers -to be link into the code. This setup also allows new ciphers -to be added by the application (with some restrictions). - -The thirteen ciphers currently defined in this library are - -EVP_CIPHER *EVP_des_ecb(); /* DES in ecb mode, iv=0, block=8, key= 8 */ -EVP_CIPHER *EVP_des_ede(); /* DES in ecb ede mode, iv=0, block=8, key=16 */ -EVP_CIPHER *EVP_des_ede3(); /* DES in ecb ede mode, iv=0, block=8, key=24 */ -EVP_CIPHER *EVP_des_cfb(); /* DES in cfb mode, iv=8, block=1, key= 8 */ -EVP_CIPHER *EVP_des_ede_cfb(); /* DES in ede cfb mode, iv=8, block=1, key=16 */ -EVP_CIPHER *EVP_des_ede3_cfb();/* DES in ede cfb mode, iv=8, block=1, key=24 */ -EVP_CIPHER *EVP_des_ofb(); /* DES in ofb mode, iv=8, block=1, key= 8 */ -EVP_CIPHER *EVP_des_ede_ofb(); /* DES in ede ofb mode, iv=8, block=1, key=16 */ -EVP_CIPHER *EVP_des_ede3_ofb();/* DES in ede ofb mode, iv=8, block=1, key=24 */ -EVP_CIPHER *EVP_des_cbc(); /* DES in cbc mode, iv=8, block=8, key= 8 */ -EVP_CIPHER *EVP_des_ede_cbc(); /* DES in cbc ede mode, iv=8, block=8, key=16 */ -EVP_CIPHER *EVP_des_ede3_cbc();/* DES in cbc ede mode, iv=8, block=8, key=24 */ -EVP_CIPHER *EVP_desx_cbc(); /* DES in desx cbc mode,iv=8, block=8, key=24 */ -EVP_CIPHER *EVP_rc4(); /* RC4, iv=0, block=1, key=16 */ -EVP_CIPHER *EVP_idea_ecb(); /* IDEA in ecb mode, iv=0, block=8, key=16 */ -EVP_CIPHER *EVP_idea_cfb(); /* IDEA in cfb mode, iv=8, block=1, key=16 */ -EVP_CIPHER *EVP_idea_ofb(); /* IDEA in ofb mode, iv=8, block=1, key=16 */ -EVP_CIPHER *EVP_idea_cbc(); /* IDEA in cbc mode, iv=8, block=8, key=16 */ -EVP_CIPHER *EVP_rc2_ecb(); /* RC2 in ecb mode, iv=0, block=8, key=16 */ -EVP_CIPHER *EVP_rc2_cfb(); /* RC2 in cfb mode, iv=8, block=1, key=16 */ -EVP_CIPHER *EVP_rc2_ofb(); /* RC2 in ofb mode, iv=8, block=1, key=16 */ -EVP_CIPHER *EVP_rc2_cbc(); /* RC2 in cbc mode, iv=8, block=8, key=16 */ -EVP_CIPHER *EVP_bf_ecb(); /* Blowfish in ecb mode,iv=0, block=8, key=16 */ -EVP_CIPHER *EVP_bf_cfb(); /* Blowfish in cfb mode,iv=8, block=1, key=16 */ -EVP_CIPHER *EVP_bf_ofb(); /* Blowfish in ofb mode,iv=8, block=1, key=16 */ -EVP_CIPHER *EVP_bf_cbc(); /* Blowfish in cbc mode,iv=8, block=8, key=16 */ - -The meaning of the compound names is as follows. -des The base cipher is DES. -idea The base cipher is IDEA -rc4 The base cipher is RC4-128 -rc2 The base cipher is RC2-128 -ecb Electronic Code Book form of the cipher. -cbc Cipher Block Chaining form of the cipher. -cfb 64 bit Cipher Feedback form of the cipher. -ofb 64 bit Output Feedback form of the cipher. -ede The cipher is used in Encrypt, Decrypt, Encrypt mode. The first - and last keys are the same. -ede3 The cipher is used in Encrypt, Decrypt, Encrypt mode. - -All the Cipher routines take a EVP_CIPHER_CTX pointer as an argument. -The state of the cipher is kept in this structure. - -typedef struct EVP_CIPHER_Ctx_st - { - EVP_CIPHER *cipher; - int encrypt; /* encrypt or decrypt */ - int buf_len; /* number we have left */ - unsigned char buf[8]; - union { - .... /* cipher specific stuff */ - } c; - } EVP_CIPHER_CTX; - -Cipher is a pointer the the EVP_CIPHER for the current context. The encrypt -flag indicates encryption or decryption. buf_len is the number of bytes -currently being held in buf. -The 'c' union holds the cipher specify context. - -The following functions are to be used. - -int EVP_read_pw_string( -char *buf, -int len, -char *prompt, -int verify, - This function is the same as des_read_pw_string() (des.doc). - -void EVP_set_pw_prompt(char *prompt); - This function sets the 'default' prompt to use to use in - EVP_read_pw_string when the prompt parameter is NULL. If the - prompt parameter is NULL, this 'default prompt' feature is turned - off. Be warned, this is a global variable so weird things - will happen if it is used under Win16 and care must be taken - with a multi-threaded version of the library. - -char *EVP_get_pw_prompt(); - This returns a pointer to the default prompt string. NULL - if it is not set. - -int EVP_BytesToKey( -EVP_CIPHER *type, -EVP_MD *md, -unsigned char *salt, -unsigned char *data, -int datal, -int count, -unsigned char *key, -unsigned char *iv); - This function is used to generate a key and an initialisation vector - for a specified cipher from a key string and a salt. Type - specifies the cipher the 'key' is being generated for. Md is the - message digest algorithm to use to generate the key and iv. The salt - is an optional 8 byte object that is used to help seed the key - generator. - If the salt value is NULL, it is just not used. Datal is the - number of bytes to use from 'data' in the key generation. - This function returns the key size for the specified cipher, if - data is NULL, this value is returns and no other - computation is performed. Count is - the number of times to loop around the key generator. I would - suggest leaving it's value as 1. Key and iv are the structures to - place the returning iv and key in. If they are NULL, no value is - generated for that particular value. - The algorithm used is as follows - - /* M[] is an array of message digests - * MD() is the message digest function */ - M[0]=MD(data . salt); - for (i=1; i<count; i++) M[0]=MD(M[0]); - - i=1 - while (data still needed for key and iv) - { - M[i]=MD(M[i-1] . data . salt); - for (i=1; i<count; i++) M[i]=MD(M[i]); - i++; - } - - If the salt is NULL, it is not used. - The digests are concatenated together. - M = M[0] . M[1] . M[2] ....... - - For key= 8, iv=8 => key=M[0.. 8], iv=M[ 9 .. 16]. - For key=16, iv=0 => key=M[0..16]. - For key=16, iv=8 => key=M[0..16], iv=M[17 .. 24]. - For key=24, iv=8 => key=M[0..24], iv=M[25 .. 32]. - - This routine will produce DES-CBC keys and iv that are compatible - with the PKCS-5 standard when md2 or md5 are used. If md5 is - used, the salt is NULL and count is 1, this routine will produce - the password to key mapping normally used with RC4. - I have attempted to logically extend the PKCS-5 standard to - generate keys and iv for ciphers that require more than 16 bytes, - if anyone knows what the correct standard is, please inform me. - When using sha or sha1, things are a bit different under this scheme, - since sha produces a 20 byte digest. So for ciphers requiring - 24 bits of data, 20 will come from the first MD and 4 will - come from the second. - - I have considered having a separate function so this 'routine' - can be used without the requirement of passing a EVP_CIPHER *, - but I have decided to not bother. If you wish to use the - function without official EVP_CIPHER structures, just declare - a local one and set the key_len and iv_len fields to the - length you desire. - -The following routines perform encryption and decryption 'by parts'. By -this I mean that there are groups of 3 routines. An Init function that is -used to specify a cipher and initialise data structures. An Update routine -that does encryption/decryption, one 'chunk' at a time. And finally a -'Final' function that finishes the encryption/decryption process. -All these functions take a EVP_CIPHER pointer to specify which cipher to -encrypt/decrypt with. They also take a EVP_CIPHER_CTX object as an -argument. This structure is used to hold the state information associated -with the operation in progress. - -void EVP_EncryptInit( -EVP_CIPHER_CTX *ctx, -EVP_CIPHER *type, -unsigned char *key, -unsigned char *iv); - This function initialise a EVP_CIPHER_CTX for encryption using the - cipher passed in the 'type' field. The cipher is initialised to use - 'key' as the key and 'iv' for the initialisation vector (if one is - required). If the type, key or iv is NULL, the value currently in the - EVP_CIPHER_CTX is reused. So to perform several decrypt - using the same cipher, key and iv, initialise with the cipher, - key and iv the first time and then for subsequent calls, - reuse 'ctx' but pass NULL for type, key and iv. You must make sure - to pass a key that is large enough for a particular cipher. I - would suggest using the EVP_BytesToKey() function. - -void EVP_EncryptUpdate( -EVP_CIPHER_CTX *ctx, -unsigned char *out, -int *outl, -unsigned char *in, -int inl); - This function takes 'inl' bytes from 'in' and outputs bytes - encrypted by the cipher 'ctx' was initialised with into 'out'. The - number of bytes written to 'out' is put into outl. If a particular - cipher encrypts in blocks, less or more bytes than input may be - output. Currently the largest block size used by supported ciphers - is 8 bytes, so 'out' should have room for 'inl+7' bytes. Normally - EVP_EncryptInit() is called once, followed by lots and lots of - calls to EVP_EncryptUpdate, followed by a single EVP_EncryptFinal - call. - -void EVP_EncryptFinal( -EVP_CIPHER_CTX *ctx, -unsigned char *out, -int *outl); - Because quite a large number of ciphers are block ciphers, there is - often an incomplete block to write out at the end of the - encryption. EVP_EncryptFinal() performs processing on this last - block. The last block in encoded in such a way that it is possible - to determine how many bytes in the last block are valid. For 8 byte - block size ciphers, if only 5 bytes in the last block are valid, the - last three bytes will be filled with the value 3. If only 2 were - valid, the other 6 would be filled with sixes. If all 8 bytes are - valid, a extra 8 bytes are appended to the cipher stream containing - nothing but 8 eights. These last bytes are output into 'out' and - the number of bytes written is put into 'outl' These last bytes - are output into 'out' and the number of bytes written is put into - 'outl'. This form of block cipher finalisation is compatible with - PKCS-5. Please remember that even if you are using ciphers like - RC4 that has no blocking and so the function will not write - anything into 'out', it would still be a good idea to pass a - variable for 'out' that can hold 8 bytes just in case the cipher is - changed some time in the future. It should also be remembered - that the EVP_CIPHER_CTX contains the password and so when one has - finished encryption with a particular EVP_CIPHER_CTX, it is good - practice to zero the structure - (ie. memset(ctx,0,sizeof(EVP_CIPHER_CTX)). - -void EVP_DecryptInit( -EVP_CIPHER_CTX *ctx, -EVP_CIPHER *type, -unsigned char *key, -unsigned char *iv); - This function is basically the same as EVP_EncryptInit() accept that - is prepares the EVP_CIPHER_CTX for decryption. - -void EVP_DecryptUpdate( -EVP_CIPHER_CTX *ctx, -unsigned char *out, -int *outl, -unsigned char *in, -int inl); - This function is basically the same as EVP_EncryptUpdate() - except that it performs decryption. There is one - fundamental difference though. 'out' can not be the same as - 'in' for any ciphers with a block size greater than 1 if more - than one call to EVP_DecryptUpdate() will be made. This - is because this routine can hold a 'partial' block between - calls. When a partial block is decrypted (due to more bytes - being passed via this function, they will be written to 'out' - overwriting the input bytes in 'in' that have not been read - yet. From this it should also be noted that 'out' should - be at least one 'block size' larger than 'inl'. This problem - only occurs on the second and subsequent call to - EVP_DecryptUpdate() when using a block cipher. - -int EVP_DecryptFinal( -EVP_CIPHER_CTX *ctx, -unsigned char *out, -int *outl); - This function is different to EVP_EncryptFinal in that it 'removes' - any padding bytes appended when the data was encrypted. Due to the - way in which 1 to 8 bytes may have been appended when encryption - using a block cipher, 'out' can end up with 0 to 7 bytes being put - into it. When decoding the padding bytes, it is possible to detect - an incorrect decryption. If the decryption appears to be wrong, 0 - is returned. If everything seems ok, 1 is returned. For ciphers - with a block size of 1 (RC4), this function would normally not - return any bytes and would always return 1. Just because this - function returns 1 does not mean the decryption was correct. It - would normally be wrong due to either the wrong key/iv or - corruption of the cipher data fed to EVP_DecryptUpdate(). - As for EVP_EncryptFinal, it is a good idea to zero the - EVP_CIPHER_CTX after use since the structure contains the key used - to decrypt the data. - -The following Cipher routines are convenience routines that call either -EVP_EncryptXxx or EVP_DecryptXxx depending on weather the EVP_CIPHER_CTX -was setup to encrypt or decrypt. - -void EVP_CipherInit( -EVP_CIPHER_CTX *ctx, -EVP_CIPHER *type, -unsigned char *key, -unsigned char *iv, -int enc); - This function take arguments that are the same as EVP_EncryptInit() - and EVP_DecryptInit() except for the extra 'enc' flag. If 1, the - EVP_CIPHER_CTX is setup for encryption, if 0, decryption. - -void EVP_CipherUpdate( -EVP_CIPHER_CTX *ctx, -unsigned char *out, -int *outl, -unsigned char *in, -int inl); - Again this function calls either EVP_EncryptUpdate() or - EVP_DecryptUpdate() depending on state in the 'ctx' structure. - As noted for EVP_DecryptUpdate(), when this routine is used - for decryption with block ciphers, 'out' should not be the - same as 'in'. - -int EVP_CipherFinal( -EVP_CIPHER_CTX *ctx, -unsigned char *outm, -int *outl); - This routine call EVP_EncryptFinal() or EVP_DecryptFinal() - depending on the state information in 'ctx'. 1 is always returned - if the mode is encryption, otherwise the return value is the return - value of EVP_DecryptFinal(). - -==== cipher.m ======================================================== - -Date: Tue, 15 Oct 1996 08:16:14 +1000 (EST) -From: Eric Young <eay@mincom.com> -X-Sender: eay@orb -To: Roland Haring <rharing@tandem.cl> -Cc: ssl-users@mincom.com -Subject: Re: Symmetric encryption with ssleay -In-Reply-To: <m0vBpyq-00001aC@tandemnet.tandem.cl> -Message-Id: <Pine.SOL.3.91.961015075623.11394A-100000@orb> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII -Sender: ssl-lists-owner@mincom.com -Precedence: bulk -Status: RO -X-Status: - -On Fri, 11 Oct 1996, Roland Haring wrote: -> THE_POINT: -> Would somebody be so kind to give me the minimum basic -> calls I need to do to libcrypto.a to get some text encrypted -> and decrypted again? ...hopefully with code included to do -> base64 encryption and decryption ... e.g. that sign-it.c code -> posted some while ago was a big help :-) (please, do not point -> me to apps/enc.c where I suspect my Heissenbug to be hidden :-) - -Ok, the base64 encoding stuff in 'enc.c' does the wrong thing sometimes -when the data is less than a line long (this is for decoding). I'll dig -up the exact fix today and post it. I am taking longer on 0.6.5 than I -intended so I'll just post this patch. - -The documentation to read is in -doc/cipher.doc, -doc/encode.doc (very sparse :-). -and perhaps -doc/digest.doc, - -The basic calls to encrypt with say triple DES are - -Given -char key[EVP_MAX_KEY_LENGTH]; -char iv[EVP_MAX_IV_LENGTH]; -EVP_CIPHER_CTX ctx; -unsigned char out[512+8]; -int outl; - -/* optional generation of key/iv data from text password using md5 - * via an upward compatable verson of PKCS#5. */ -EVP_BytesToKey(EVP_des_ede3_cbc,EVP_md5,NULL,passwd,strlen(passwd), - key,iv); - -/* Initalise the EVP_CIPHER_CTX */ -EVP_EncryptInit(ctx,EVP_des_ede3_cbc,key,iv); - -while (....) - { - /* This is processing 512 bytes at a time, the bytes are being - * copied into 'out', outl bytes are output. 'out' should not be the - * same as 'in' for reasons mentioned in the documentation. */ - EVP_EncryptUpdate(ctx,out,&outl,in,512); - } - -/* Output the last 'block'. If the cipher is a block cipher, the last - * block is encoded in such a way so that a wrong decryption will normally be - * detected - again, one of the PKCS standards. */ - -EVP_EncryptFinal(ctx,out,&outl); - -To decrypt, use the EVP_DecryptXXXXX functions except that EVP_DecryptFinal() -will return 0 if the decryption fails (only detectable on block ciphers). - -You can also use -EVP_CipherInit() -EVP_CipherUpdate() -EVP_CipherFinal() -which does either encryption or decryption depending on an extra -parameter to EVP_CipherInit(). - - -To do the base64 encoding, -EVP_EncodeInit() -EVP_EncodeUpdate() -EVP_EncodeFinal() - -EVP_DecodeInit() -EVP_DecodeUpdate() -EVP_DecodeFinal() - -where the encoding is quite simple, but the decoding can be a bit more -fun (due to dud input). - -EVP_DecodeUpdate() returns -1 for an error on an input line, 0 if the -'last line' was just processed, and 1 if more lines should be submitted. - -EVP_DecodeFinal() returns -1 for an error or 1 if things are ok. - -So the loop becomes -EVP_DecodeInit(....) -for (;;) - { - i=EVP_DecodeUpdate(....); - if (i < 0) goto err; - - /* process the data */ - - if (i == 0) break; - } -EVP_DecodeFinal(....); -/* process the data */ - -The problem in 'enc.c' is that I was stuff the processing up after the -EVP_DecodeFinal(...) when the for(..) loop was not being run (one line of -base64 data) and this was because 'enc.c' tries to scan over a file until -it hits the first valid base64 encoded line. - -hope this helps a bit. -eric --- -Eric Young | BOOL is tri-state according to Bill Gates. -AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). - -==== conf.doc ======================================================== - -The CONF library. - -The CONF library is a simple set of routines that can be used to configure -programs. It is a superset of the genenv() function with some extra -structure. - -The library consists of 5 functions. - -LHASH *CONF_load(LHASH *config,char *file); -This function is called to load in a configuration file. Multiple -configuration files can be loaded, with each subsequent 'load' overwriting -any already defined 'variables'. If there is an error, NULL is returned. -If config is NULL, a new LHASH structure is created and returned, otherwise -the new data in the 'file' is loaded into the 'config' structure. - -void CONF_free(LHASH *config); -This function free()s the data in config. - -char *CONF_get_string(LHASH *config,char *section,char *name); -This function returns the string found in 'config' that corresponds to the -'section' and 'name' specified. Classes and the naming system used will be -discussed later in this document. If the variable is not defined, an NULL -is returned. - -long CONF_get_long(LHASH *config,char *section, char *name); -This function is the same as CONF_get_string() except that it converts the -string to an long and returns it. If variable is not a number or the -variable does not exist, 0 is returned. This is a little problematic but I -don't know of a simple way around it. - -STACK *CONF_get_section(LHASH *config, char *section); -This function returns a 'stack' of CONF_VALUE items that are all the -items defined in a particular section. DO NOT free() any of the -variable returned. They will disappear when CONF_free() is called. - -The 'lookup' model. -The configuration file is divided into 'sections'. Each section is started by -a line of the form '[ section ]'. All subsequent variable definitions are -of this section. A variable definition is a simple alpha-numeric name -followed by an '=' and then the data. A section or variable name can be -described by a regular expression of the following form '[A-Za-z0-9_]+'. -The value of the variable is the text after the '=' until the end of the -line, stripped of leading and trailing white space. -At this point I should mention that a '#' is a comment character, \ is the -escape character, and all three types of quote can be used to stop any -special interpretation of the data. -Now when the data is being loaded, variable expansion can occur. This is -done by expanding any $NAME sequences into the value represented by the -variable NAME. If the variable is not in the current section, the different -section can be specified by using the $SECTION::NAME form. The ${NAME} form -also works and is very useful for expanding variables inside strings. - -When a variable is looked up, there are 2 special section. 'default', which -is the initial section, and 'ENV' which is the processes environment -variables (accessed via getenv()). When a variable is looked up, it is -first 'matched' with it's section (if one was specified), if this fails, the -'default' section is matched. -If the 'lhash' variable passed was NULL, the environment is searched. - -Now why do we bother with sections? So we can have multiple programs using -the same configuration file, or multiple instances of the same program -using different variables. It also provides a nice mechanism to override -the processes environment variables (eg ENV::HOME=/tmp). If there is a -program specific variable missing, we can have default values. -Multiple configuration files can be loaded, with each new value clearing -any predefined values. A system config file can provide 'default' values, -and application/usr specific files can provide overriding values. - -Examples - -# This is a simple example -SSLEAY_HOME = /usr/local/ssl -ENV::PATH = $SSLEAY_HOME/bin:$PATH # override my path - -[X509] -cert_dir = $SSLEAY_HOME/certs # /usr/local/ssl/certs - -[SSL] -CIPHER = DES-EDE-MD5:RC4-MD5 -USER_CERT = $HOME/${USER}di'r 5' # /home/eay/eaydir 5 -USER_CERT = $HOME/\${USER}di\'r # /home/eay/${USER}di'r -USER_CERT = "$HOME/${US"ER}di\'r # $HOME/${USER}di'r - -TEST = 1234\ -5678\ -9ab # TEST=123456789ab -TTT = 1234\n\n # TTT=1234<nl><nl> - - - -==== des.doc ======================================================== - -The DES library. - -Please note that this library was originally written to operate with -eBones, a version of Kerberos that had had encryption removed when it left -the USA and then put back in. As such there are some routines that I will -advise not using but they are still in the library for historical reasons. -For all calls that have an 'input' and 'output' variables, they can be the -same. - -This library requires the inclusion of 'des.h'. - -All of the encryption functions take what is called a des_key_schedule as an -argument. A des_key_schedule is an expanded form of the des key. -A des_key is 8 bytes of odd parity, the type used to hold the key is a -des_cblock. A des_cblock is an array of 8 bytes, often in this library -description I will refer to input bytes when the function specifies -des_cblock's as input or output, this just means that the variable should -be a multiple of 8 bytes. - -The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to -specify decryption. The functions and global variable are as follows: - -int des_check_key; - DES keys are supposed to be odd parity. If this variable is set to - a non-zero value, des_set_key() will check that the key has odd - parity and is not one of the known weak DES keys. By default this - variable is turned off; - -void des_set_odd_parity( -des_cblock *key ); - This function takes a DES key (8 bytes) and sets the parity to odd. - -int des_is_weak_key( -des_cblock *key ); - This function returns a non-zero value if the DES key passed is a - weak, DES key. If it is a weak key, don't use it, try a different - one. If you are using 'random' keys, the chances of hitting a weak - key are 1/2^52 so it is probably not worth checking for them. - -int des_set_key( -des_cblock *key, -des_key_schedule schedule); - Des_set_key converts an 8 byte DES key into a des_key_schedule. - A des_key_schedule is an expanded form of the key which is used to - perform actual encryption. It can be regenerated from the DES key - so it only needs to be kept when encryption or decryption is about - to occur. Don't save or pass around des_key_schedule's since they - are CPU architecture dependent, DES keys are not. If des_check_key - is non zero, zero is returned if the key has the wrong parity or - the key is a weak key, else 1 is returned. - -int des_key_sched( -des_cblock *key, -des_key_schedule schedule); - An alternative name for des_set_key(). - -int des_rw_mode; /* defaults to DES_PCBC_MODE */ - This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default). - This specifies the function to use in the enc_read() and enc_write() - functions. - -void des_encrypt( -unsigned long *data, -des_key_schedule ks, -int enc); - This is the DES encryption function that gets called by just about - every other DES routine in the library. You should not use this - function except to implement 'modes' of DES. I say this because the - functions that call this routine do the conversion from 'char *' to - long, and this needs to be done to make sure 'non-aligned' memory - access do not occur. The characters are loaded 'little endian', - have a look at my source code for more details on how I use this - function. - Data is a pointer to 2 unsigned long's and ks is the - des_key_schedule to use. enc, is non zero specifies encryption, - zero if decryption. - -void des_encrypt2( -unsigned long *data, -des_key_schedule ks, -int enc); - This functions is the same as des_encrypt() except that the DES - initial permutation (IP) and final permutation (FP) have been left - out. As for des_encrypt(), you should not use this function. - It is used by the routines in my library that implement triple DES. - IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same - as des_encrypt() des_encrypt() des_encrypt() except faster :-). - -void des_ecb_encrypt( -des_cblock *input, -des_cblock *output, -des_key_schedule ks, -int enc); - This is the basic Electronic Code Book form of DES, the most basic - form. Input is encrypted into output using the key represented by - ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise - decryption occurs. Input is 8 bytes long and output is 8 bytes. - (the des_cblock structure is 8 chars). - -void des_ecb3_encrypt( -des_cblock *input, -des_cblock *output, -des_key_schedule ks1, -des_key_schedule ks2, -des_key_schedule ks3, -int enc); - This is the 3 key EDE mode of ECB DES. What this means is that - the 8 bytes of input is encrypted with ks1, decrypted with ks2 and - then encrypted again with ks3, before being put into output; - C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt() - that only takes 2 des_key_schedules that implements, - C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1. - -void des_cbc_encrypt( -des_cblock *input, -des_cblock *output, -long length, -des_key_schedule ks, -des_cblock *ivec, -int enc); - This routine implements DES in Cipher Block Chaining mode. - Input, which should be a multiple of 8 bytes is encrypted - (or decrypted) to output which will also be a multiple of 8 bytes. - The number of bytes is in length (and from what I've said above, - should be a multiple of 8). If length is not a multiple of 8, I'm - not being held responsible :-). ivec is the initialisation vector. - This function does not modify this variable. To correctly implement - cbc mode, you need to do one of 2 things; copy the last 8 bytes of - cipher text for use as the next ivec in your application, - or use des_ncbc_encrypt(). - Only this routine has this problem with updating the ivec, all - other routines that are implementing cbc mode update ivec. - -void des_ncbc_encrypt( -des_cblock *input, -des_cblock *output, -long length, -des_key_schedule sk, -des_cblock *ivec, -int enc); - For historical reasons, des_cbc_encrypt() did not update the - ivec with the value requires so that subsequent calls to - des_cbc_encrypt() would 'chain'. This was needed so that the same - 'length' values would not need to be used when decrypting. - des_ncbc_encrypt() does the right thing. It is the same as - des_cbc_encrypt accept that ivec is updates with the correct value - to pass in subsequent calls to des_ncbc_encrypt(). I advise using - des_ncbc_encrypt() instead of des_cbc_encrypt(); - -void des_xcbc_encrypt( -des_cblock *input, -des_cblock *output, -long length, -des_key_schedule sk, -des_cblock *ivec, -des_cblock *inw, -des_cblock *outw, -int enc); - This is RSA's DESX mode of DES. It uses inw and outw to - 'whiten' the encryption. inw and outw are secret (unlike the iv) - and are as such, part of the key. So the key is sort of 24 bytes. - This is much better than cbc des. - -void des_3cbc_encrypt( -des_cblock *input, -des_cblock *output, -long length, -des_key_schedule sk1, -des_key_schedule sk2, -des_cblock *ivec1, -des_cblock *ivec2, -int enc); - This function is flawed, do not use it. I have left it in the - library because it is used in my des(1) program and will function - correctly when used by des(1). If I removed the function, people - could end up unable to decrypt files. - This routine implements outer triple cbc encryption using 2 ks and - 2 ivec's. Use des_ede2_cbc_encrypt() instead. - -void des_ede3_cbc_encrypt( -des_cblock *input, -des_cblock *output, -long length, -des_key_schedule ks1, -des_key_schedule ks2, -des_key_schedule ks3, -des_cblock *ivec, -int enc); - This function implements outer triple CBC DES encryption with 3 - keys. What this means is that each 'DES' operation - inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))). - Again, this is cbc mode so an ivec is requires. - This mode is used by SSL. - There is also a des_ede2_cbc_encrypt() that only uses 2 - des_key_schedule's, the first being reused for the final - encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES - is used by the RSAref library. - -void des_pcbc_encrypt( -des_cblock *input, -des_cblock *output, -long length, -des_key_schedule ks, -des_cblock *ivec, -int enc); - This is Propagating Cipher Block Chaining mode of DES. It is used - by Kerberos v4. It's parameters are the same as des_ncbc_encrypt(). - -void des_cfb_encrypt( -unsigned char *in, -unsigned char *out, -int numbits, -long length, -des_key_schedule ks, -des_cblock *ivec, -int enc); - Cipher Feedback Back mode of DES. This implementation 'feeds back' - in numbit blocks. The input (and output) is in multiples of numbits - bits. numbits should to be a multiple of 8 bits. Length is the - number of bytes input. If numbits is not a multiple of 8 bits, - the extra bits in the bytes will be considered padding. So if - numbits is 12, for each 2 input bytes, the 4 high bits of the - second byte will be ignored. So to encode 72 bits when using - a numbits of 12 take 12 bytes. To encode 72 bits when using - numbits of 9 will take 16 bytes. To encode 80 bits when using - numbits of 16 will take 10 bytes. etc, etc. This padding will - apply to both input and output. - - -void des_cfb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -des_key_schedule ks, -des_cblock *ivec, -int *num, -int enc); - This is one of the more useful functions in this DES library, it - 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 :-). - -void des_ede3_cfb64_encrypt( -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); - Same as des_cfb64_encrypt() accept that the DES operation is - triple DES. As usual, there is a macro for - des_ede2_cfb64_encrypt() which reuses ks1. - -void des_ofb_encrypt( -unsigned char *in, -unsigned char *out, -int numbits, -long length, -des_key_schedule ks, -des_cblock *ivec); - This is a implementation of Output Feed Back mode of DES. It is - the same as des_cfb_encrypt() in that numbits is the size of the - units dealt with during input and output (in bits). - -void des_ofb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -des_key_schedule ks, -des_cblock *ivec, -int *num); - The same as des_cfb64_encrypt() except that it is Output Feed Back - mode. - -void des_ede3_ofb64_encrypt( -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); - Same as des_ofb64_encrypt() accept that the DES operation is - triple DES. As usual, there is a macro for - des_ede2_ofb64_encrypt() which reuses ks1. - -int des_read_pw_string( -char *buf, -int length, -char *prompt, -int verify); - This routine is used to get a password from the terminal with echo - turned off. Buf is where the string will end up and length is the - size of buf. Prompt is a string presented to the 'user' and if - verify is set, the key is asked for twice and unless the 2 copies - match, an error is returned. A return code of -1 indicates a - system error, 1 failure due to use interaction, and 0 is success. - -unsigned long des_cbc_cksum( -des_cblock *input, -des_cblock *output, -long length, -des_key_schedule ks, -des_cblock *ivec); - This function produces an 8 byte checksum from input that it puts in - output and returns the last 4 bytes as a long. The checksum is - generated via cbc mode of DES in which only the last 8 byes are - kept. I would recommend not using this function but instead using - the EVP_Digest routines, or at least using MD5 or SHA. This - function is used by Kerberos v4 so that is why it stays in the - library. - -char *des_fcrypt( -const char *buf, -const char *salt -char *ret); - This is my 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. - -char *crypt( -const char *buf, -const char *salt); - This function calls des_fcrypt() with a static array passed as the - third parameter. This emulates the normal non-thread safe semantics - of crypt(3). - -void des_string_to_key( -char *str, -des_cblock *key); - This function takes str and converts it into a DES key. I would - recommend using MD5 instead and use the first 8 bytes of output. - When I wrote the first version of these routines back in 1990, MD5 - did not exist but I feel these routines are still sound. This - routines is compatible with the one in MIT's libdes. - -void des_string_to_2keys( -char *str, -des_cblock *key1, -des_cblock *key2); - This function takes str and converts it into 2 DES keys. - I would recommend using MD5 and using the 16 bytes as the 2 keys. - I have nothing against these 2 'string_to_key' routines, it's just - that if you say that your encryption key is generated by using the - 16 bytes of an MD5 hash, every-one knows how you generated your - keys. - -int des_read_password( -des_cblock *key, -char *prompt, -int verify); - This routine combines des_read_pw_string() with des_string_to_key(). - -int des_read_2passwords( -des_cblock *key1, -des_cblock *key2, -char *prompt, -int verify); - This routine combines des_read_pw_string() with des_string_to_2key(). - -void des_random_seed( -des_cblock key); - This routine sets a starting point for des_random_key(). - -void des_random_key( -des_cblock ret); - This function return a random key. Make sure to 'seed' the random - number generator (with des_random_seed()) before using this function. - I personally now use a MD5 based random number system. - -int des_enc_read( -int fd, -char *buf, -int len, -des_key_schedule ks, -des_cblock *iv); - This function will write to a file descriptor the encrypted data - from buf. This data will be preceded by a 4 byte 'byte count' and - will be padded out to 8 bytes. The encryption is either CBC of - PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE, - pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use - DES_PCBC_MODE. - -int des_enc_write( -int fd, -char *buf, -int len, -des_key_schedule ks, -des_cblock *iv); - This routines read stuff written by des_enc_read() and decrypts it. - I have used these routines quite a lot but I don't believe they are - suitable for non-blocking io. If you are after a full - authentication/encryption over networks, have a look at SSL instead. - -unsigned long des_quad_cksum( -des_cblock *input, -des_cblock *output, -long length, -int out_count, -des_cblock *seed); - This is a function from Kerberos v4 that is not anything to do with - DES but was needed. It is a cksum that is quicker to generate than - des_cbc_cksum(); I personally would use MD5 routines now. -===== -Modes of DES -Quite a bit of the following information has been taken from - 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 - -There are several different modes in which DES can be used, they are -as follows. - -Electronic Codebook Mode (ECB) (des_ecb_encrypt()) -- 64 bits are enciphered at a time. -- The order of the blocks can be rearranged without detection. -- The same plaintext block always produces the same ciphertext block - (for the same key) making it vulnerable to a 'dictionary attack'. -- An error will only affect one ciphertext block. - -Cipher Block Chaining Mode (CBC) (des_cbc_encrypt()) -- a multiple of 64 bits are enciphered at a time. -- The CBC mode produces the same ciphertext whenever the same - plaintext is encrypted using the same key and starting variable. -- The chaining operation makes the ciphertext blocks dependent on the - current and all preceding plaintext blocks and therefore blocks can not - be rearranged. -- The use of different starting variables prevents the same plaintext - enciphering to the same ciphertext. -- An error will affect the current and the following ciphertext blocks. - -Cipher Feedback Mode (CFB) (des_cfb_encrypt()) -- a number of bits (j) <= 64 are enciphered at a time. -- The CFB mode produces the same ciphertext whenever the same - plaintext is encrypted using the same key and starting variable. -- 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. -- The use of different starting variables prevents the same plaintext - enciphering to the same ciphertext. -- The strength of the CFB mode depends on the size of k (maximal if - j == k). In my implementation this is always the case. -- 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. -- Only multiples of j bits can be enciphered. -- An error will affect the current and the following ciphertext variables. - -Output Feedback Mode (OFB) (des_ofb_encrypt()) -- a number of bits (j) <= 64 are enciphered at a time. -- 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. -- The absence of chaining makes the OFB more vulnerable to specific attacks. -- The use of different start variables values prevents the same - plaintext enciphering to the same ciphertext, by producing different - key streams. -- 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. -- Only multiples of j bits can be enciphered. -- 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. -- OFB mode is not self-synchronising. If the two operation of - encipherment and decipherment get out of synchronism, the system needs - to be re-initialised. -- Each re-initialisation 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. - -Triple ECB Mode (des_ecb3_encrypt()) -- Encrypt with key1, decrypt with key2 and encrypt with key3 again. -- 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. -- If both keys are the same it is equivalent to encrypting once with - just one key. -- If the first and last key are the same, the key length is 112 bits. - There are attacks that could reduce the key space to 55 bit's but it - requires 2^56 blocks of memory. -- If all 3 keys are the same, this is effectively the same as normal - ecb mode. - -Triple CBC Mode (des_ede3_cbc_encrypt()) -- Encrypt with key1, decrypt with key2 and then encrypt with key3. -- As for CBC encryption but increases the key length to 168 bits with - the same restrictions as for triple ecb mode. - -==== digest.doc ======================================================== - - -The Message Digest subroutines. - -These routines require "evp.h" to be included. - -These functions are a higher level interface to the various message digest -routines found in this library. As such, they allow the same code to be -used to digest via different algorithms with only a change in an initial -parameter. They are basically just a front-end to the MD2, MD5, SHA -and SHA1 -routines. - -These routines all take a pointer to the following structure to specify -which message digest algorithm to use. -typedef struct evp_md_st - { - int type; - int pkey_type; - int md_size; - void (*init)(); - void (*update)(); - void (*final)(); - - int required_pkey_type; /*EVP_PKEY_xxx */ - int (*sign)(); - int (*verify)(); - } EVP_MD; - -If additional message digest algorithms are to be supported, a structure of -this type needs to be declared and populated and then the Digest routines -can be used with that algorithm. The type field is the object NID of the -digest type (read the section on Objects for an explanation). The pkey_type -is the Object type to use when the a message digest is generated by there -routines and then is to be signed with the pkey algorithm. Md_size is -the size of the message digest returned. Init, update -and final are the relevant functions to perform the message digest function -by parts. One reason for specifying the message digest to use via this -mechanism is that if you only use md5, only the md5 routines will -be included in you linked program. If you passed an integer -that specified which message digest to use, the routine that mapped that -integer to a set of message digest functions would cause all the message -digests functions to be link into the code. This setup also allows new -message digest functions to be added by the application. - -The six message digests defined in this library are - -EVP_MD *EVP_md2(void); /* RSA sign/verify */ -EVP_MD *EVP_md5(void); /* RSA sign/verify */ -EVP_MD *EVP_sha(void); /* RSA sign/verify */ -EVP_MD *EVP_sha1(void); /* RSA sign/verify */ -EVP_MD *EVP_dss(void); /* DSA sign/verify */ -EVP_MD *EVP_dss1(void); /* DSA sign/verify */ - -All the message digest routines take a EVP_MD_CTX pointer as an argument. -The state of the message digest is kept in this structure. - -typedef struct pem_md_ctx_st - { - EVP_MD *digest; - union { - unsigned char base[4]; /* this is used in my library as a - * 'pointer' to all union elements - * structures. */ - MD2_CTX md2; - MD5_CTX md5; - SHA_CTX sha; - } md; - } EVP_MD_CTX; - -The Digest functions are as follows. - -void EVP_DigestInit( -EVP_MD_CTX *ctx, -EVP_MD *type); - This function is used to initialise the EVP_MD_CTX. The message - digest that will associated with 'ctx' is specified by 'type'. - -void EVP_DigestUpdate( -EVP_MD_CTX *ctx, -unsigned char *data, -unsigned int cnt); - This function is used to pass more data to the message digest - function. 'cnt' bytes are digested from 'data'. - -void EVP_DigestFinal( -EVP_MD_CTX *ctx, -unsigned char *md, -unsigned int *len); - This function finishes the digestion and puts the message digest - into 'md'. The length of the message digest is put into len; - EVP_MAX_MD_SIZE is the size of the largest message digest that - can be returned from this function. Len can be NULL if the - size of the digest is not required. - - -==== encode.doc ======================================================== - - -void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); -void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out, - int *outl,unsigned char *in,int inl); -void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl); -int EVP_EncodeBlock(unsigned char *t, unsigned char *f, int n); - -void EVP_DecodeInit(EVP_ENCODE_CTX *ctx); -int EVP_DecodeUpdate(EVP_ENCODE_CTX *ctx,unsigned char *out,int *outl, - unsigned char *in, int inl); -int EVP_DecodeFinal(EVP_ENCODE_CTX *ctx, unsigned - char *out, int *outl); -int EVP_DecodeBlock(unsigned char *t, unsigned - char *f, int n); - - -==== envelope.doc ======================================================== - -The following routines are use to create 'digital' envelopes. -By this I mean that they perform various 'higher' level cryptographic -functions. Have a read of 'cipher.doc' and 'digest.doc' since those -routines are used by these functions. -cipher.doc contains documentation about the cipher part of the -envelope library and digest.doc contatins the description of the -message digests supported. - -To 'sign' a document involves generating a message digest and then encrypting -the digest with an private key. - -#define EVP_SignInit(a,b) EVP_DigestInit(a,b) -#define EVP_SignUpdate(a,b,c) EVP_DigestUpdate(a,b,c) -Due to the fact this operation is basically just an extended message -digest, the first 2 functions are macro calls to Digest generating -functions. - -int EVP_SignFinal( -EVP_MD_CTX *ctx, -unsigned char *md, -unsigned int *s, -EVP_PKEY *pkey); - This finalisation function finishes the generation of the message -digest and then encrypts the digest (with the correct message digest -object identifier) with the EVP_PKEY private key. 'ctx' is the message digest -context. 'md' will end up containing the encrypted message digest. This -array needs to be EVP_PKEY_size(pkey) bytes long. 's' will actually -contain the exact length. 'pkey' of course is the private key. It is -one of EVP_PKEY_RSA or EVP_PKEY_DSA type. -If there is an error, 0 is returned, otherwise 1. - -Verify is used to check an signed message digest. - -#define EVP_VerifyInit(a,b) EVP_DigestInit(a,b) -#define EVP_VerifyUpdate(a,b,c) EVP_DigestUpdate(a,b,c) -Since the first step is to generate a message digest, the first 2 functions -are macros. - -int EVP_VerifyFinal( -EVP_MD_CTX *ctx, -unsigned char *md, -unsigned int s, -EVP_PKEY *pkey); - This function finishes the generation of the message digest and then -compares it with the supplied encrypted message digest. 'md' contains the -'s' bytes of encrypted message digest. 'pkey' is used to public key decrypt -the digest. It is then compared with the message digest just generated. -If they match, 1 is returned else 0. - -int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek, - int *ekl, unsigned char *iv, EVP_PKEY **pubk, int npubk); -Must have at least one public key, error is 0. I should also mention that -the buffers pointed to by 'ek' need to be EVP_PKEY_size(pubk[n]) is size. - -#define EVP_SealUpdate(a,b,c,d,e) EVP_EncryptUpdate(a,b,c,d,e) -void EVP_SealFinal(EVP_CIPHER_CTX *ctx,unsigned char *out,int *outl); - - -int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, - int ekl,unsigned char *iv,EVP_PKEY *priv); -0 on failure - -#define EVP_OpenUpdate(a,b,c,d,e) EVP_DecryptUpdate(a,b,c,d,e) - -int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); -Decrypt final return code - - -==== error.doc ======================================================== - -The error routines. - -The 'error' system I've implemented is intended to server 2 purpose, to -record the reason why a command failed and to record where in the libraries -the failure occurred. It is more or less setup to record a 'trace' of which -library components were being traversed when the error occurred. - -When an error is recorded, it is done so a as single unsigned long which is -composed of three parts. The top byte is the 'library' number, the middle -12 bytes is the function code, and the bottom 12 bits is the 'reason' code. - -Each 'library', or should a say, 'section' of the SSLeay library has a -different unique 'library' error number. Each function in the library has -a number that is unique for that library. Each 'library' also has a number -for each 'error reason' that is only unique for that 'library'. - -Due to the way these error routines record a 'error trace', there is an -array per thread that is used to store the error codes. -The various functions in this library are used to access -and manipulate this array. - -void ERR_put_error(int lib, int func,int reason); - This routine records an error in library 'lib', function 'func' -and reason 'reason'. As errors get 'put' into the buffer, they wrap -around and overwrite old errors if too many are written. It is assumed -that the last errors are the most important. - -unsigned long ERR_get_error(void ); - This function returns the last error added to the error buffer. -In effect it is popping the value off the buffer so repeated calls will -continue to return values until there are no more errors to return in which -case 0 is returned. - -unsigned long ERR_peek_error(void ); - This function returns the value of the last error added to the -error buffer but does not 'pop' it from the buffer. - -void ERR_clear_error(void ); - This function clears the error buffer, discarding all unread -errors. - -While the above described error system obviously produces lots of different -error number, a method for 'reporting' these errors in a human readable -form is required. To achieve this, each library has the option of -'registering' error strings. - -typedef struct ERR_string_data_st - { - unsigned long error; - char *string; - } ERR_STRING_DATA; - -The 'ERR_STRING_DATA' contains an error code and the corresponding text -string. To add new function error strings for a library, the -ERR_STRING_DATA needs to be 'registered' with the library. - -void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err); - This function 'registers' the array of ERR_STRING_DATA pointed to by -'err' as error text strings for the error library 'lib'. - -void ERR_free_strings(void); - This function free()s all the loaded error strings. - -char *ERR_error_string(unsigned long error,char *buf); - This function returns a text string that is a human readable -version of the error represented by 'error'. Buff should be at least 120 -bytes long and if it is NULL, the return value is a pointer to a static -variable that will contain the error string, otherwise 'buf' is returned. -If there is not a text string registered for a particular error, a text -string containing the error number is returned instead. - -void ERR_print_errors(BIO *bp); -void ERR_print_errors_fp(FILE *fp); - This function is a convenience routine that prints the error string -for each error until all errors have been accounted for. - -char *ERR_lib_error_string(unsigned long e); -char *ERR_func_error_string(unsigned long e); -char *ERR_reason_error_string(unsigned long e); -The above three functions return the 3 different components strings for the -error 'e'. ERR_error_string() uses these functions. - -void ERR_load_ERR_strings(void ); - This function 'registers' the error strings for the 'ERR' module. - -void ERR_load_crypto_strings(void ); - This function 'register' the error strings for just about every -library in the SSLeay package except for the SSL routines. There is no -need to ever register any error text strings and you will probably save in -program size. If on the other hand you do 'register' all errors, it is -quite easy to determine why a particular routine failed. - -As a final footnote as to why the error system is designed as it is. -1) I did not want a single 'global' error code. -2) I wanted to know which subroutine a failure occurred in. -3) For Windows NT etc, it should be simple to replace the 'key' routines - with code to pass error codes back to the application. -4) I wanted the option of meaningful error text strings. - -Late breaking news - the changes to support threads. - -Each 'thread' has an 'ERR_STATE' state associated with it. -ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling -thread/process. - -ERR_remove_state(unsigned long pid); will 'free()' this state. If pid == 0 -the current 'thread/process' will have it's error state removed. -If you do not remove the error state of a thread, this could be considered a -form of memory leak, so just after 'reaping' a thread that has died, -call ERR_remove_state(pid). - -Have a read of thread.doc for more details for what is required for -multi-threading support. All the other error routines will -work correctly when using threads. - - -==== idea.doc ======================================================== - -The IDEA library. -IDEA is a block cipher that operates on 64bit (8 byte) quantities. It -uses a 128bit (16 byte) key. It can be used in all the modes that DES can -be used. This library implements the ecb, cbc, cfb64 and ofb64 modes. - -For all calls that have an 'input' and 'output' variables, they can be the -same. - -This library requires the inclusion of 'idea.h'. - -All of the encryption functions take what is called an IDEA_KEY_SCHEDULE as an -argument. An IDEA_KEY_SCHEDULE is an expanded form of the idea key. -For all modes of the IDEA algorithm, the IDEA_KEY_SCHEDULE used for -decryption is different to the one used for encryption. - -The define IDEA_ENCRYPT is passed to specify encryption for the functions -that require an encryption/decryption flag. IDEA_DECRYPT is passed to -specify decryption. For some mode there is no encryption/decryption -flag since this is determined by the IDEA_KEY_SCHEDULE. - -So to encrypt you would do the following -idea_set_encrypt_key(key,encrypt_ks); -idea_ecb_encrypt(...,encrypt_ks); -idea_cbc_encrypt(....,encrypt_ks,...,IDEA_ENCRYPT); - -To Decrypt -idea_set_encrypt_key(key,encrypt_ks); -idea_set_decrypt_key(encrypt_ks,decrypt_ks); -idea_ecb_encrypt(...,decrypt_ks); -idea_cbc_encrypt(....,decrypt_ks,...,IDEA_DECRYPT); - -Please note that any of the encryption modes specified in my DES library -could be used with IDEA. I have only implemented ecb, cbc, cfb64 and -ofb64 for the following reasons. -- ecb is the basic IDEA encryption. -- cbc is the normal 'chaining' form for block ciphers. -- cfb64 can be used to encrypt single characters, therefore input and output - do not need to be a multiple of 8. -- ofb64 is similar to cfb64 but is more like a stream cipher, not as - secure (not cipher feedback) but it does not have an encrypt/decrypt mode. -- If you want triple IDEA, thats 384 bits of key and you must be totally - obsessed with security. Still, if you want it, it is simple enough to - copy the function from the DES library and change the des_encrypt to - idea_encrypt; an exercise left for the paranoid reader :-). - -The functions are as follows: - -void idea_set_encrypt_key( -unsigned char *key; -IDEA_KEY_SCHEDULE *ks); - idea_set_encrypt_key converts a 16 byte IDEA key into an - IDEA_KEY_SCHEDULE. The IDEA_KEY_SCHEDULE is an expanded form of - the key which can be used to perform IDEA encryption. - An IDEA_KEY_SCHEDULE is an expanded form of the key which is used to - perform actual encryption. It can be regenerated from the IDEA key - so it only needs to be kept when encryption is about - to occur. Don't save or pass around IDEA_KEY_SCHEDULE's since they - are CPU architecture dependent, IDEA keys are not. - -void idea_set_decrypt_key( -IDEA_KEY_SCHEDULE *encrypt_ks, -IDEA_KEY_SCHEDULE *decrypt_ks); - This functions converts an encryption IDEA_KEY_SCHEDULE into a - decryption IDEA_KEY_SCHEDULE. For all decryption, this conversion - of the key must be done. In some modes of IDEA, an - encryption/decryption flag is also required, this is because these - functions involve block chaining and the way this is done changes - depending on which of encryption of decryption is being done. - Please note that there is no quick way to generate the decryption - key schedule other than generating the encryption key schedule and - then converting it. - -void idea_encrypt( -unsigned long *data, -IDEA_KEY_SCHEDULE *ks); - This is the IDEA encryption function that gets called by just about - every other IDEA routine in the library. You should not use this - function except to implement 'modes' of IDEA. I say this because the - functions that call this routine do the conversion from 'char *' to - long, and this needs to be done to make sure 'non-aligned' memory - access do not occur. - Data is a pointer to 2 unsigned long's and ks is the - IDEA_KEY_SCHEDULE to use. Encryption or decryption depends on the - IDEA_KEY_SCHEDULE. - -void idea_ecb_encrypt( -unsigned char *input, -unsigned char *output, -IDEA_KEY_SCHEDULE *ks); - This is the basic Electronic Code Book form of IDEA (in DES this - mode is called Electronic Code Book so I'm going to use the term - for idea as well :-). - Input is encrypted into output using the key represented by - ks. Depending on the IDEA_KEY_SCHEDULE, encryption or - decryption occurs. Input is 8 bytes long and output is 8 bytes. - -void idea_cbc_encrypt( -unsigned char *input, -unsigned char *output, -long length, -IDEA_KEY_SCHEDULE *ks, -unsigned char *ivec, -int enc); - This routine implements IDEA in Cipher Block Chaining mode. - Input, which should be a multiple of 8 bytes is encrypted - (or decrypted) to output which will also be a multiple of 8 bytes. - The number of bytes is in length (and from what I've said above, - should be a multiple of 8). If length is not a multiple of 8, bad - things will probably happen. ivec is the initialisation vector. - This function updates iv after each call so that it can be passed to - the next call to idea_cbc_encrypt(). - -void idea_cfb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -des_key_schedule ks, -des_cblock *ivec, -int *num, -int enc); - This is one of the more useful functions in this IDEA library, it - implements CFB mode of IDEA with 64bit feedback. - This allows you to encrypt an arbitrary number of bytes, - you do not require 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. - Enc is used to indicate encryption or decryption. - One very important thing to remember is that when decrypting, use - the encryption form of the key. - CFB64 mode operates by using the cipher to - generate a stream of bytes which is used to encrypt the plain text. - The cipher text is then encrypted to generate the next 64 bits to - be xored (incrementally) with the next 64 bits of plain - text. As can be seen from this, to encrypt or decrypt, - the same 'cipher stream' needs to be generated but the way the next - block of data is gathered for encryption is different for - encryption and decryption. What this means is that to encrypt - idea_set_encrypt_key(key,ks); - idea_cfb64_encrypt(...,ks,..,IDEA_ENCRYPT) - do decrypt - idea_set_encrypt_key(key,ks) - idea_cfb64_encrypt(...,ks,...,IDEA_DECRYPT) - Note: The same IDEA_KEY_SCHEDULE but different encryption flags. - For idea_cbc or idea_ecb, idea_set_decrypt_key() would need to be - used to generate the IDEA_KEY_SCHEDULE for decryption. - The reason I'm stressing this point is that I just wasted 3 hours - today trying to decrypt using this mode and the decryption form of - the key :-(. - -void idea_ofb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -des_key_schedule ks, -des_cblock *ivec, -int *num); - This functions implements OFB mode of IDEA with 64bit feedback. - This allows you to encrypt an arbitrary number of bytes, - you do not require 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. - This is in effect a stream cipher, there is no encryption or - decryption mode. The same key and iv should be used to - encrypt and decrypt. - -For reading passwords, I suggest using des_read_pw_string() from my DES library. -To generate a password from a text string, I suggest using MD5 (or MD2) to -produce a 16 byte message digest that can then be passed directly to -idea_set_encrypt_key(). - -===== -For more information about the specific IDEA modes in this library -(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the -documentation on my DES library. What is said about DES is directly -applicable for IDEA. - - -==== legal.doc ======================================================== - -From eay@mincom.com Thu Jun 27 00:25:45 1996 -Received: by orb.mincom.oz.au id AA15821 - (5.65c/IDA-1.4.4 for eay); Wed, 26 Jun 1996 14:25:45 +1000 -Date: Wed, 26 Jun 1996 14:25:45 +1000 (EST) -From: Eric Young <eay@mincom.oz.au> -X-Sender: eay@orb -To: Ken Toll <ktoll@ren.digitalage.com> -Cc: Eric Young <eay@mincom.oz.au>, ssl-talk@netscape.com -Subject: Re: Unidentified subject! -In-Reply-To: <9606261950.ZM28943@ren.digitalage.com> -Message-Id: <Pine.SOL.3.91.960626131156.28573K-100000@orb> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII -Status: O -X-Status: - - -This is a little off topic but since SSLeay is a free implementation of -the SSLv2 protocol, I feel it is worth responding on the topic of if it -is actually legal for Americans to use free cryptographic software. - -On Wed, 26 Jun 1996, Ken Toll wrote: -> Is the U.S the only country that SSLeay cannot be used commercially -> (because of RSAref) or is that going to be an issue with every country -> that a client/server application (non-web browser/server) is deployed -> and sold? - ->From what I understand, the software patents that apply to algorithms -like RSA and DH only apply in the USA. The IDEA algorithm I believe is -patened in europe (USA?), but considing how little it is used by other SSL -implementations, it quite easily be left out of the SSLeay build -(this can be done with a compile flag). - -Actually if the RSA patent did apply outside the USA, it could be rather -interesting since RSA is not alowed to let RSA toolkits outside of the USA -[1], and since these are the only forms that they will alow the algorithm -to be used in, it would mean that non-one outside of the USA could produce -public key software which would be a very strong statment for -international patent law to make :-). This logic is a little flawed but -it still points out some of the more interesting permutations of USA -patent law and ITAR restrictions. - -Inside the USA there is also the unresolved issue of RC4/RC2 which were -made public on sci.crypt in Sep 1994 (RC4) and Feb 1996 (RC2). I have -copies of the origional postings if people are interested. RSA I believe -claim that they were 'trade-secrets' and that some-one broke an NDA in -revealing them. Other claim they reverse engineered the algorithms from -compiled binaries. If the algorithms were reverse engineered, I believe -RSA had no legal leg to stand on. If an NDA was broken, I don't know. -Regardless, RSA, I believe, is willing to go to court over the issue so -licencing is probably the best idea, or at least talk to them. -If there are people who actually know more about this, pease let me know, I -don't want to vilify or spread miss-information if I can help it. - -If you are not producing a web browser, it is easy to build SSLeay with -RC2/RC4 removed. Since RC4 is the defacto standard cipher in -all web software (and it is damn fast) it is more or less required for -www use. For non www use of SSL, especially for an application where -interoperability with other vendors is not critical just leave it out. - -Removing IDEA, RC2 and RC4 would only leave DES and Triple DES but -they should be ok. Considing that Triple DES can encrypt at rates of -410k/sec on a pentium 100, and 940k/sec on a P6/200, this is quite -reasonable performance. Single DES clocks in at 1160k/s and 2467k/s -respectivly is actually quite fast for those not so paranoid (56 bit key).[1] - -> Is it possible to get a certificate for commercial use outside of the U.S.? -yes. - -Thawte Consulting issues certificates (they are the people who sell the - Sioux httpd server and are based in South Africa) -Verisign will issue certificates for Sioux (sold from South Africa), so this - proves that they will issue certificate for OS use if they are - happy with the quality of the software. - -(The above mentioned companies just the ones that I know for sure are issuing - certificates outside the USA). - -There is always the point that if you are using SSL for an intra net, -SSLeay provides programs that can be used so you can issue your own -certificates. They need polishing but at least it is a good starting point. - -I am not doing anything outside Australian law by implementing these -algorithms (to the best of my knowedge). It is another example of how -the world legal system does not cope with the internet very well. - -I may start making shared libraries available (I have now got DLL's for -Windows). This will mean that distributions into the usa could be -shipped with a version with a reduced cipher set and the versions outside -could use the DLL/shared library with all the ciphers (and without RSAref). - -This could be completly hidden from the application, so this would not -even require a re-linking. - -This is the reverse of what people were talking about doing to get around -USA export regulations :-) - -eric - -[1]: The RSAref2.0 tookit is available on at least 3 ftp sites in Europe - and one in South Africa. - -[2]: Since I always get questions when I post benchmark numbers :-), - DES performace figures are in 1000's of bytes per second in cbc - mode using an 8192 byte buffer. The pentium 100 was running Windows NT - 3.51 DLLs and the 686/200 was running NextStep. - I quote pentium 100 benchmarks because it is basically the - 'entry level' computer that most people buy for personal use. - Windows 95 is the OS shipping on those boxes, so I'll give - NT numbers (the same Win32 runtime environment). The 686 - numbers are present as an indication of where we will be in a - few years. --- -Eric Young | BOOL is tri-state according to Bill Gates. -AARNet: eay@mincom.oz.au | RTFM Win32 GetMessage(). - - - -==== lhash.doc ======================================================== - -The LHASH library. - -I wrote this library in 1991 and have since forgotten why I called it lhash. -It implements a hash table from an article I read at the -time from 'Communications of the ACM'. What makes this hash -table different is that as the table fills, the hash table is -increased (or decreased) in size via realloc(). -When a 'resize' is done, instead of all hashes being redistributed over -twice as many 'buckets', one bucket is split. So when an 'expand' is done, -there is only a minimal cost to redistribute some values. Subsequent -inserts will cause more single 'bucket' redistributions but there will -never be a sudden large cost due to redistributing all the 'buckets'. - -The state for a particular hash table is kept in the LHASH structure. -The LHASH structure also records statistics about most aspects of accessing -the hash table. This is mostly a legacy of my writing this library for -the reasons of implementing what looked like a nice algorithm rather than -for a particular software product. - -Internal stuff you probably don't want to know about. -The decision to increase or decrease the hash table size is made depending -on the 'load' of the hash table. The load is the number of items in the -hash table divided by the size of the hash table. The default values are -as follows. If (hash->up_load < load) => expand. -if (hash->down_load > load) => contract. The 'up_load' has a default value of -1 and 'down_load' has a default value of 2. These numbers can be modified -by the application by just playing with the 'up_load' and 'down_load' -variables. The 'load' is kept in a form which is multiplied by 256. So -hash->up_load=8*256; will cause a load of 8 to be set. - -If you are interested in performance the field to watch is -num_comp_calls. The hash library keeps track of the 'hash' value for -each item so when a lookup is done, the 'hashes' are compared, if -there is a match, then a full compare is done, and -hash->num_comp_calls is incremented. If num_comp_calls is not equal -to num_delete plus num_retrieve it means that your hash function is -generating hashes that are the same for different values. It is -probably worth changing your hash function if this is the case because -even if your hash table has 10 items in a 'bucked', it can be searched -with 10 'unsigned long' compares and 10 linked list traverses. This -will be much less expensive that 10 calls to you compare function. - -LHASH *lh_new( -unsigned long (*hash)(), -int (*cmp)()); - This function is used to create a new LHASH structure. It is passed - function pointers that are used to store and retrieve values passed - into the hash table. The 'hash' - function is a hashing function that will return a hashed value of - it's passed structure. 'cmp' is passed 2 parameters, it returns 0 - is they are equal, otherwise, non zero. - If there are any problems (usually malloc failures), NULL is - returned, otherwise a new LHASH structure is returned. The - hash value is normally truncated to a power of 2, so make sure - that your hash function returns well mixed low order bits. - -void lh_free( -LHASH *lh); - This function free()s a LHASH structure. If there is malloced - data in the hash table, it will not be freed. Consider using the - lh_doall function to deallocate any remaining entries in the hash - table. - -char *lh_insert( -LHASH *lh, -char *data); - This function inserts the data pointed to by data into the lh hash - table. If there is already and entry in the hash table entry, the - value being replaced is returned. A NULL is returned if the new - entry does not clash with an entry already in the table (the normal - case) or on a malloc() failure (perhaps I should change this....). - The 'char *data' is exactly what is passed to the hash and - comparison functions specified in lh_new(). - -char *lh_delete( -LHASH *lh, -char *data); - This routine deletes an entry from the hash table. The value being - deleted is returned. NULL is returned if there is no such value in - the hash table. - -char *lh_retrieve( -LHASH *lh, -char *data); - If 'data' is in the hash table it is returned, else NULL is - returned. The way these routines would normally be uses is that a - dummy structure would have key fields populated and then - ret=lh_retrieve(hash,&dummy);. Ret would now be a pointer to a fully - populated structure. - -void lh_doall( -LHASH *lh, -void (*func)(char *a)); - This function will, for every entry in the hash table, call function - 'func' with the data item as parameters. - This function can be quite useful when used as follows. - void cleanup(STUFF *a) - { STUFF_free(a); } - lh_doall(hash,cleanup); - lh_free(hash); - This can be used to free all the entries, lh_free() then - cleans up the 'buckets' that point to nothing. Be careful - when doing this. If you delete entries from the hash table, - in the call back function, the table may decrease in size, - moving item that you are - currently on down lower in the hash table. This could cause - some entries to be skipped. The best solution to this problem - is to set lh->down_load=0 before you start. This will stop - the hash table ever being decreased in size. - -void lh_doall_arg( -LHASH *lh; -void(*func)(char *a,char *arg)); -char *arg; - This function is the same as lh_doall except that the function - called will be passed 'arg' as the second argument. - -unsigned long lh_strhash( -char *c); - This function is a demo string hashing function. Since the LHASH - routines would normally be passed structures, this routine would - not normally be passed to lh_new(), rather it would be used in the - function passed to lh_new(). - -The next three routines print out various statistics about the state of the -passed hash table. These numbers are all kept in the lhash structure. - -void lh_stats( -LHASH *lh, -FILE *out); - This function 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. - -void lh_node_stats( -LHASH *lh, -FILE *out); - For each 'bucket' in the hash table, the number of entries is - printed. - -void lh_node_usage_stats( -LHASH *lh, -FILE *out); - This function prints out a short summary of the state of the hash - table. It prints what I call 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. - -==== md2.doc ======================================================== - -The MD2 library. -MD2 is a message digest algorithm that can be used to condense an arbitrary -length message down to a 16 byte hash. The functions all need to be passed -a MD2_CTX which is used to hold the MD2 context during multiple MD2_Update() -function calls. The normal method of use for this library is as follows - -MD2_Init(...); -MD2_Update(...); -... -MD2_Update(...); -MD2_Final(...); - -This library requires the inclusion of 'md2.h'. - -The main negative about MD2 is that it is slow, especially when compared -to MD5. - -The functions are as follows: - -void MD2_Init( -MD2_CTX *c); - This function needs to be called to initiate a MD2_CTX structure for - use. - -void MD2_Update( -MD2_CTX *c; -unsigned char *data; -unsigned long len); - This updates the message digest context being generated with 'len' - bytes from the 'data' pointer. The number of bytes can be any - length. - -void MD2_Final( -unsigned char *md; -MD2_CTX *c; - This function is called when a message digest of the data digested - with MD2_Update() is wanted. The message digest is put in the 'md' - array and is MD2_DIGEST_LENGTH (16) bytes long. - -unsigned char *MD2( -unsigned long n; -unsigned char *d; -unsigned char *md; - This function performs a MD2_Init(), followed by a MD2_Update() - followed by a MD2_Final() (using a local MD2_CTX). - The resulting digest is put into 'md' if it is not NULL. - Regardless of the value of 'md', the message - digest is returned from the function. If 'md' was NULL, the message - digest returned is being stored in a static structure. - -==== md5.doc ======================================================== - -The MD5 library. -MD5 is a message digest algorithm that can be used to condense an arbitrary -length message down to a 16 byte hash. The functions all need to be passed -a MD5_CTX which is used to hold the MD5 context during multiple MD5_Update() -function calls. This library also contains random number routines that are -based on MD5 - -The normal method of use for this library is as follows - -MD5_Init(...); -MD5_Update(...); -... -MD5_Update(...); -MD5_Final(...); - -This library requires the inclusion of 'md5.h'. - -The functions are as follows: - -void MD5_Init( -MD5_CTX *c); - This function needs to be called to initiate a MD5_CTX structure for - use. - -void MD5_Update( -MD5_CTX *c; -unsigned char *data; -unsigned long len); - This updates the message digest context being generated with 'len' - bytes from the 'data' pointer. The number of bytes can be any - length. - -void MD5_Final( -unsigned char *md; -MD5_CTX *c; - This function is called when a message digest of the data digested - with MD5_Update() is wanted. The message digest is put in the 'md' - array and is MD5_DIGEST_LENGTH (16) bytes long. - -unsigned char *MD5( -unsigned char *d; -unsigned long n; -unsigned char *md; - This function performs a MD5_Init(), followed by a MD5_Update() - followed by a MD5_Final() (using a local MD5_CTX). - The resulting digest is put into 'md' if it is not NULL. - Regardless of the value of 'md', the message - digest is returned from the function. If 'md' was NULL, the message - digest returned is being stored in a static structure. - - -==== memory.doc ======================================================== - -In the interests of debugging SSLeay, there is an option to compile -using some simple memory leak checking. - -All malloc(), free() and realloc() calls in SSLeay now go via -Malloc(), Free() and Realloc() (except those in crypto/lhash). - -If CRYPTO_MDEBUG is defined, these calls are #defined to -CRYPTO_malloc(), CRYPTO_free() and CRYPTO_realloc(). -If it is not defined, they are #defined to malloc(), free() and realloc(). - -the CRYPTO_malloc() routines by default just call the underlying library -functons. - -If CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_ON) is called, memory leak detection is -turned on. CRYPTO_mem_ctrl(CRYPTO_MEM_CHECK_OFF) turns it off. - -When turned on, each Malloc() or Realloc() call is recored along with the file -and line number from where the call was made. (This is done using the -lhash library which always uses normal system malloc(3) routines). - -void CRYPTO_mem_leaks(BIO *b); -void CRYPTO_mem_leaks_fp(FILE *fp); -These both print out the list of memory that has not been free()ed. -This will probably be rather hard to read, but if you look for the 'top level' -structure allocation, this will often give an idea as to what is not being -free()ed. I don't expect people to use this stuff normally. - -==== ca.1 ======================================================== - -From eay@orb.mincom.oz.au Thu Dec 28 23:56:45 1995 -Received: by orb.mincom.oz.au id AA07374 - (5.65c/IDA-1.4.4 for eay); Thu, 28 Dec 1995 13:56:45 +1000 -Date: Thu, 28 Dec 1995 13:56:45 +1000 (EST) -From: Eric Young <eay@mincom.oz.au> -X-Sender: eay@orb -To: sameer <sameer@c2.org> -Cc: ssleay@mincom.oz.au -Subject: Re: 'ca' -In-Reply-To: <199512230440.UAA23410@infinity.c2.org> -Message-Id: <Pine.SOL.3.91.951228133525.7269A-100000@orb> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII -Status: RO -X-Status: - -On Fri, 22 Dec 1995, sameer wrote: -> I could use documentation on 'ca'. Thanks. - -Very quickly. -The ca program uses the ssleay.conf file for most of its configuration - -./ca -help - - -verbose - Talk alot while doing things - -config file - A config file. If you don't want to use the - default config file - -name arg - The particular CA definition to use - In the config file, the section to use for parameters. This lets - multiple setups to be contained in the one file. By default, the - default_ca variable is looked up in the [ ca ] section. So in the - shipped ssleay.conf, the CA definition used is CA_default. It could be - any other name. - -gencrl days - Generate a new CRL, days is when the next CRL is due - This will generate a new certificate revocion list. - -days arg - number of days to certify the certificate for - When certifiying certificates, this is the number of days to use. - -md arg - md to use, one of md2, md5, sha or sha1 - -policy arg - The CA 'policy' to support - I'll describe this later, but there are 2 policies definied in the - shipped ssleay.conf - -keyfile arg - PEM RSA private key file - -key arg - key to decode the RSA private key if it is encrypted - since we need to keep the CA's RSA key encrypted - -cert - The CA certificate - -in file - The input PEM encoded certificate request(s) - -out file - Where to put the output file(s) - -outdir dir - Where to put output certificates - The -out options concatinates all the output certificied - certificates to one file, -outdir puts them in a directory, - named by serial number. - -infiles .... - The last argument, requests to process - The certificate requests to process, -in is the same. - -Just about all the above have default values defined in ssleay.conf. - -The key variables in ssleay.conf are (for the pariticular '-name' being -used, in the default, it is CA_default). - -dir is where all the CA database stuff is kept. -certs is where all the previously issued certificates are kept. -The database is a simple text database containing the following tab separated -fields. -status: a value of 'R' - revoked, 'E' -expired or 'V' valid. -issued date: When the certificate was certified. -revoked date: When it was revoked, blank if not revoked. -serial number: The certificate serial number. -certificate: Where the certificate is located. -CN: The name of the certificate. - -The demo file has quite a few made up values it it. The last 2 were -added by the ca program and are acurate. -The CA program does not update the 'certificate' file correctly right now. -The serial field should be unique as should the CN/status combination. -The ca program checks these at startup. What still needs to be -wrtten is a program to 'regenerate' the data base file from the issued -certificate list (and a CRL list). - -Back to the CA_default variables. - -Most of the variables are commented. - -policy is the default policy. - -Ok for policies, they define the order and which fields must be present -in the certificate request and what gets filled in. - -So a value of -countryName = match -means that the country name must match the CA certificate. -organizationalUnitName = optional -The org.Unit,Name does not have to be present and -commonName = supplied -commonName must be supplied in the certificate request. - -For the 'policy_match' polocy, the order of the attributes in the -generated certiticate would be -countryName -stateOrProvinceName -organizationName -organizationalUnitName -commonName -emailAddress - -Have a play, it sort of makes sense. If you think about how the persona -requests operate, it is similar to the 'policy_match' policy and the -'policy_anything' is similar to what versign is doing. - -I hope this helps a bit. Some backend scripts are definitly needed to -update the database and to make certificate revocion easy. All -certificates issued should also be kept forever (or until they expire?) - -hope this helps -eric (who has to run off an buy some cheap knee pads for the caving in 4 -days time :-) - --- -Eric Young | Signature removed since it was generating -AARNet: eay@mincom.oz.au | more followups than the message contents :-) - - -==== ms3-ca.doc ======================================================== - -Date: Mon, 9 Jun 97 08:00:33 +0200 -From: Holger.Reif@PrakInf.TU-Ilmenau.DE (Holger Reif) -Subject: ms3-ca.doc -Organization: TU Ilmenau, Fak. IA, FG Telematik -Content-Length: 14575 -Status: RO -X-Status: - -Loading client certs into MSIE 3.01 -=================================== - -This document contains all the information necessary to successfully set up -some scripts to issue client certs to Microsoft Internet Explorer. It -includes the required knowledge about the model MSIE uses for client -certification and includes complete sample scripts ready to play with. The -scripts were tested against a modified ca program of SSLeay 0.6.6 and should -work with the regular ca program that comes with version 0.8.0. I haven't -tested against MSIE 4.0 - -You can use the information contained in this document in either way you -want. However if you feel it saved you a lot of time I ask you to be as fair -as to mention my name: Holger Reif <reif@prakinf.tu-ilmenau.de>. - -1.) The model used by MSIE --------------------------- - -The Internet Explorer doesn't come with a embedded engine for installing -client certs like Netscape's Navigator. It rather uses the CryptoAPI (CAPI) -defined by Microsoft. CAPI comes with WindowsNT 4.0 or is installed together -with Internet Explorer since 3.01. The advantage of this approach is a higher -flexibility because the certificates in the (per user) system open -certificate store may be used by other applications as well. The drawback -however is that you need to do a bit more work to get a client cert issued. - -CAPI defines functions which will handle basic cryptographic work, eg. -generating keys, encrypting some data, signing text or building a certificate -request. The procedure is as follows: A CAPI function generates you a key -pair and saves it into the certificate store. After that one builds a -Distinguished Name. Together with that key pair another CAPI function forms a -PKCS#10 request which you somehow need to submit to a CA. Finally the issued -cert is given to a yet another CAPI function which saves it into the -certificate store. - -The certificate store with the user's keys and certs is in the registry. You -will find it under HKEY_CURRENT_USER/Software/Microsoft/Cryptography/ (I -leave it to you as a little exercise to figure out what all the entries mean -;-). Note that the keys are protected only with the user's usual Windows -login password. - -2.) The practical usage ------------------------ - -Unfortunatly since CAPI is a system API you can't access its functions from -HTML code directly. For this purpose Microsoft provides a wrapper called -certenr3.dll. This DLL accesses the CAPI functions and provides an interface -usable from Visual Basic Script. One needs to install that library on the -computer which wants to have client cert. The easiest way is to load it as an -ActiveX control (certenr3.dll is properly authenticode signed by MS ;-). If -you have ever enrolled e cert request at a CA you will have installed it. - -At time of writing certenr3.dll is contained in -http://www.microsoft.com/workshop/prog/security/csa/certenr3.exe. It comes -with an README file which explains the available functions. It is labeled -beta but every CA seems to use it anyway. The license.txt allows you the -usage for your own purposes (as far as I understood) and a somehow limited -distribution. - -The two functions of main interest are GenerateKeyPair and AcceptCredentials. -For complete explanation of all possible parameters see the README file. Here -are only minimal required parameters and their values. - -GenerateKeyPair(sessionID, FASLE, szName, 0, "ClientAuth", TRUE, FALSE, 1) -- sessionID is a (locally to that computer) unique string to correlate the -generated key pair with a cert installed later. -- szName is the DN of the form "C=DE; S=Thueringen; L=Ilmenau; CN=Holger -Reif; 1.2.840.113549.1.9.1=reif@prakinf.tu-ilmenau.de". Note that S is the -abreviation for StateOrProvince. The recognized abreviation include CN, O, C, -OU, G, I, L, S, T. If the abreviation is unknown (eg. for PKCS#9 email addr) -you need to use the full object identifier. The starting point for searching -them could be crypto/objects.h since all OIDs know to SSLeay are listed -there. -- note: the possible ninth parameter which should give a default name to the -certificate storage location doesn't seem to work. Changes to the constant -values in the call above doesn't seem to make sense. You can't generate -PKCS#10 extensions with that function. - -The result of GenerateKeyPair is the base64 encoded PKCS#10 request. However -it has a little strange format that SSLeay doesn't accept. (BTW I feel the -decision of rejecting that format as standard conforming.) It looks like -follows: - 1st line with 76 chars - 2nd line with 76 chars - ... - (n-2)th line with 76 chars - (n-1)th line contains a multiple of 4 chars less then 76 (possible -empty) - (n)th line has zero or 4 chars (then with 1 or 2 equal signs - the - original text's lenght wasn'T a multiple of 3) - The line separator has two chars: 0x0d 0x0a - -AcceptCredentials(sessionID, credentials, 0, FALSE) -- sessionID needs to be the same as while generating the key pair -- credentials is the base64 encoded PKCS#7 object containing the cert. - -CRL's and CA certs are not required simply just the client cert. (It seems to -me that both are not even checked somehow.) The only format of the base64 -encoded object I succesfully used was all characters in a very long string -without line feeds or carriage returns. (Hey, it doesn't matter, only a -computer reads it!) - -The result should be S_OK. For error handling see the example that comes with -certenr3.dll. - -A note about ASN.1 character encodings. certenr3.dll seems to know only about -2 of them: UniversalString and PrintableString. First it is definitely wrong -for an email address which is IA5STRING (checked by ssleay's ca). Second -unfortunately MSIE (at least until version 3.02) can't handle UniversalString -correctly - they just blow up you cert store! Therefore ssleay's ca (starting -from version 0.8.0) tries to convert the encodings automatically to IA5STRING -or TeletexString. The beef is it will work only for the latin-1 (western) -charset. Microsoft still has to do abit of homework... - -3.) An example --------------- - -At least you need two steps: generating the key & request and then installing -the certificate. A real world CA would have some more steps involved, eg. -accepting some license. Note that both scripts shown below are just -experimental state without any warrenty! - -First how to generate a request. Note that we can't use a static page because -of the sessionID. I generate it from system time plus pid and hope it is -unique enough. Your are free to feed it through md5 to get more impressive -ID's ;-) Then the intended text is read in with sed which inserts the -sessionID. - ------BEGIN ms-enroll.cgi----- -#!/bin/sh -SESSION_ID=`date '+%y%m%d%H%M%S'`$$ -echo Content-type: text/html -echo -sed s/template_for_sessId/$SESSION_ID/ <<EOF -<HTML><HEAD> -<TITLE>Certificate Enrollment Test Page</TITLE> -</HEAD><BODY> - -<OBJECT - classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43" - codebase=certenr3.dll - id=certHelper - > -</OBJECT> - -<CENTER> -<H2>enrollment for a personal cert</H2> -<BR><HR WIDTH=50%><BR><P> -<FORM NAME="MSIE_Enrollment" ACTION="ms-gencert.cgi" ENCTYPE=x-www-form- -encoded METHOD=POST> -<TABLE> - <TR><TD>Country</TD><TD><INPUT NAME="Country" VALUE=""></TD></TR> - <TR><TD>State</TD><TD><INPUT NAME="StateOrProvince" VALUE=""></TD></TR> - <TR><TD>Location</TD><TD><INPUT NAME="Location" VALUE=""></TD></TR> - <TR><TD>Organization</TD><TD><INPUT NAME="Organization" -VALUE=""></TD></TR> - <TR><TD>Organizational Unit</TD> - <TD><INPUT NAME="OrganizationalUnit" VALUE=""></TD></TR> - <TR><TD>Name</TD><TD><INPUT NAME="CommonName" VALUE=""></TD></TR> - <TR><TD>eMail Address</TD> - <TD><INPUT NAME="EmailAddress" VALUE=""></TD></TR> - <TR><TD></TD> - <TD><INPUT TYPE="BUTTON" NAME="submit" VALUE="Beantragen"></TD></TR> -</TABLE> - <INPUT TYPE="hidden" NAME="SessionId" VALUE="template_for_sessId"> - <INPUT TYPE="hidden" NAME="Request" VALUE=""> -</FORM> -<BR><HR WIDTH=50%><BR><P> -</CENTER> - -<SCRIPT LANGUAGE=VBS> - Dim DN - - Sub Submit_OnClick - Dim TheForm - Set TheForm = Document.MSIE_Enrollment - sessionId = TheForm.SessionId.value - reqHardware = FALSE - C = TheForm.Country.value - SP = TheForm.StateOrProvince.value - L = TheForm.Location.value - O = TheForm.Organization.value - OU = TheForm.OrganizationalUnit.value - CN = TheForm.CommonName.value - Email = TheForm.EmailAddress.value - szPurpose = "ClientAuth" - doAcceptanceUINow = FALSE - doOnline = TRUE - - DN = "" - - Call Add_RDN("C", C) - Call Add_RDN("S", SP) - Call Add_RDN("L", L) - Call Add_RDN("O", O) - Call Add_RDN("OU", OU) - Call Add_RDN("CN", CN) - Call Add_RDN("1.2.840.113549.1.9.1", Email) - ' rsadsi - ' pkcs - ' pkcs9 - ' eMailAddress - On Error Resume Next - sz10 = certHelper.GenerateKeyPair(sessionId, _ - FALSE, DN, 0, ClientAuth, FASLE, TRUE, 1)_ - theError = Err.Number - On Error Goto 0 - if (sz10 = Empty OR theError <> 0) Then - sz = "The error '" & Hex(theError) & "' occurred." & chr(13) & _ - chr(10) & "Your credentials could not be generated." - result = MsgBox(sz, 0, "Credentials Enrollment") - Exit Sub - else - TheForm.Request.value = sz10 - TheForm.Submit - end if - End Sub - - Sub Add_RDN(sn, value) - if (value <> "") then - if (DN <> "") then - DN = DN & "; " - end if - DN = DN & sn & "=" & value - end if - End Sub -</SCRIPT> -</BODY> -</HTML> -EOF ------END ms-enroll.cgi----- - -Second, how to extract the request and feed the certificate back? We need to -"normalize" the base64 encoding of the PKCS#10 format which means -regenerating the lines and wrapping with BEGIN and END line. This is done by -gawk. The request is taken by ca the normal way. Then the cert needs to be -packed into a PKCS#7 structure (note: the use of a CRL is necessary for -crl2pkcs7 as of version 0.6.6. Starting with 0.8.0 it it might probably be -ommited). Finally we need to format the PKCS#7 object and generate the HTML -text. I use two templates to have a clearer script. - -1st note: postit2 is slightly modified from a program I found at ncsa's ftp -site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You -need utils.c from there too. - -2nd note: I'm note quite sure wether the gawk script really handles all -possible inputs for the request right! Today I don't use this construction -anymore myself. - -3d note: the cert must be of version 3! This could be done with the nsComment -line in ssleay.cnf... - -------BEGIN ms-gencert.cgi----- -#!/bin/sh -FILE="/tmp/"`date '+%y%m%d%H%M%S'-`$$ -rm -f "$FILE".* - -HOME=`pwd`; export HOME # as ssleay.cnf insists on having such an env var -cd /usr/local/ssl #where demoCA (as named in ssleay.conf) is located - -postit2 -s " " -i 0x0d > "$FILE".inp # process the FORM vars - -SESSION_ID=`gawk '$1 == "SessionId" { print $2; exit }' "$FILE".inp` - -gawk \ - 'BEGIN { \ - OFS = ""; \ - print "-----BEGIN CERTIFICATE REQUEST-----"; \ - req_seen=0 \ - } \ - $1 == "Request" { \ - req_seen=1; \ - if (length($2) == 72) print($2); \ - lastline=$2; \ - next; \ - } \ - { \ - if (req_seen == 1) { \ - if (length($1) >= 72) print($1); \ - else if (length(lastline) < 72) { \ - req_seen=0; \ - print (lastline,$1); \ - } \ - lastline=$1; \ - } \ - } \ - END { \ - print "-----END CERTIFICATE REQUEST-----"; \ - }' > "$FILE".pem < "$FILE".inp - -ssleay ca -batch -in "$FILE".pem -key passwd -out "$FILE".out -ssleay crl2pkcs7 -certfile "$FILE".out -out "$FILE".pkcs7 -in demoCA/crl.pem - -sed s/template_for_sessId/$SESSION_ID/ <ms-enroll2a.html >"$FILE".cert -/usr/local/bin/gawk \ - 'BEGIN { \ - OFS = ""; \ - dq = sprintf("%c",34); \ - } \ - $0 ~ "PKCS7" { next; } \ - { \ - print dq$0dq" & _"; \ - }' <"$FILE".pkcs7 >> "$FILE".cert -cat ms-enroll2b.html >>"$FILE".cert - -echo Content-type: text/html -echo Content-length: `wc -c "$FILE".cert` -echo -cat "$FILE".cert -rm -f "$FILE".* ------END ms-gencert.cgi----- - -----BEGIN ms-enroll2a.html---- -<HTML><HEAD><TITLE>Certificate Acceptance Test Page</TITLE></HEAD><BODY> - -<OBJECT - classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43" - codebase=certenr3.dll - id=certHelper - > -</OBJECT> - -<CENTER> -<H2>Your personal certificate</H2> -<BR><HR WIDTH=50%><BR><P> -Press the button! -<P><INPUT TYPE=BUTTON VALUE="Nimm mich!" NAME="InstallCert"> -</CENTER> -<BR><HR WIDTH=50%><BR> - -<SCRIPT LANGUAGE=VBS> - Sub InstallCert_OnClick - - sessionId = "template_for_sessId" -credentials = "" & _ -----END ms-enroll2a.html---- - -----BEGIN ms-enroll2b.html---- -"" - On Error Resume Next - result = certHelper.AcceptCredentials(sessionId, credentials, 0, -FALSE) - if (IsEmpty(result)) Then - sz = "The error '" & Err.Number & "' occurred." & chr(13) & -chr(10) & "This Digital ID could not be registered." - msgOut = MsgBox(sz, 0, "Credentials Registration Error") - navigate "error.html" - else - sz = "Digital ID successfully registered." - msgOut = MsgBox(sz, 0, "Credentials Registration") - navigate "success.html" - end if - Exit Sub - End Sub -</SCRIPT> -</BODY> -</HTML> -----END ms-enroll2b.html---- - -4.) What do do with the cert? ------------------------------ - -The cert is visible (without restarting MSIE) under the following menu: -View->Options->Security->Personal certs. You can examine it's contents at -least partially. - -To use it for client authentication you need to use SSL3.0 (fortunately -SSLeay supports it with 0.8.0). Furthermore MSIE is told to only supports a -kind of automatic selection of certs (I personally wasn't able to test it -myself). But there is a requirement that the issuer of the server cert and -the issuer of the client cert needs to be the same (according to a developer -from MS). Which means: you need may more then one cert to talk to all -servers... - -I'm sure we will get a bit more experience after ApacheSSL is available for -SSLeay 0.8.8. - - -I hope you enjoyed reading and that in future questions on this topic will -rarely appear on ssl-users@moncom.com ;-) - -Ilmenau, 9th of June 1997 -Holger Reif <reif@prakinf.tu-ilmenau.de> --- -read you later - Holger Reif ----------------------------------------- Signaturprojekt Deutsche Einheit -TU Ilmenau - Informatik - Telematik (Verdamp lang her) -Holger.Reif@PrakInf.TU-Ilmenau.DE Alt wie ein Baum werden, um ueber -http://Remus.PrakInf.TU-Ilmenau.DE/Reif/ alle 7 Bruecken gehen zu koennen - - -==== ns-ca.doc ======================================================== - -The following documentation was supplied by Jeff Barber, who provided the -patch to the CA program to add this functionality. - -eric --- -Jeff Barber Email: jeffb@issl.atl.hp.com - -Hewlett Packard Phone: (404) 648-9503 -Internet and System Security Lab Fax: (404) 648-9516 - - oo ----------------------cut /\ here for ns-ca.doc ------------------------------ - -This document briefly describes how to use SSLeay to implement a -certificate authority capable of dynamically serving up client -certificates for version 3.0 beta 5 (and presumably later) versions of -the Netscape Navigator. Before describing how this is done, it's -important to understand a little about how the browser implements its -client certificate support. This is documented in some detail in the -URLs based at <URL:http://home.netscape.com/eng/security/certs.html>. -Here's a brief overview: - -- The Navigator supports a new HTML tag "KEYGEN" which will cause - the browser to generate an RSA key pair when you submit a form - containing the tag. The public key, along with an optional - challenge (supposedly provided for use in certificate revocation - but I don't use it) is signed, DER-encoded, base-64 encoded - and sent to the web server as the value of the variable - whose NAME is provided in the KEYGEN tag. The private key is - stored by the browser in a local key database. - - This "Signed Public Key And Challenge" (SPKAC) arrives formatted - into 64 character lines (which are of course URL-encoded when - sent via HTTP -- i.e. spaces, newlines and most punctuatation are - encoded as "%HH" where HH is the hex equivalent of the ASCII code). - Note that the SPKAC does not contain the other usual attributes - of a certificate request, especially the subject name fields. - These must be otherwise encoded in the form for submission along - with the SPKAC. - -- Either immediately (in response to this form submission), or at - some later date (a real CA will probably verify your identity in - some way before issuing the certificate), a web server can send a - certificate based on the public key and other attributes back to - the browser by encoding it in DER (the binary form) and sending it - to the browser as MIME type: - "Content-type: application/x-x509-user-cert" - - The browser uses the public key encoded in the certificate to - associate the certificate with the appropriate private key in - its local key database. Now, the certificate is "installed". - -- When a server wants to require authentication based on client - certificates, it uses the right signals via the SSL protocol to - trigger the Navigator to ask you which certificate you want to - send. Whether the certificate is accepted is dependent on CA - certificates and so forth installed in the server and is beyond - the scope of this document. - - -Now, here's how the SSLeay package can be used to provide client -certficates: - -- You prepare a file for input to the SSLeay ca application. - The file contains a number of "name = value" pairs that identify - the subject. The names here are the same subject name component - identifiers used in the CA section of the lib/ssleay.conf file, - such as "emailAddress", "commonName" "organizationName" and so - forth. Both the long version and the short version (e.g. "Email", - "CN", "O") can be used. - - One more name is supported: this one is "SPKAC". Its value - is simply the value of the base-64 encoded SPKAC sent by the - browser (with all the newlines and other space charaters - removed -- and newline escapes are NOT supported). - - [ As of SSLeay 0.6.4, multiple lines are supported. - Put a \ at the end of each line and it will be joined with the - previous line with the '\n' removed - eay ] - - Here's a sample input file: - -C = US -SP = Georgia -O = Some Organization, Inc. -OU = Netscape Compatibility Group -CN = John X. Doe -Email = jxdoe@someorg.com -SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx - -- You execute the ca command (either from a CGI program run out of - the web server, or as a later manual task) giving it the above - file as input. For example, if the file were named /tmp/cert.req, - you'd run: - $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert - - The output is in DER format (binary) if a -out argument is - provided, as above; otherwise, it's in the PEM format (base-64 - encoded DER). Also, the "-batch" switch is implied by the - "-spkac" so you don't get asked whether to complete the signing - (probably it shouldn't work this way but I was only interested - in hacking together an online CA that could be used for issuing - test certificates). - - The "-spkac" capability doesn't support multiple files (I think). - - Any CHALLENGE provided in the SPKAC is simply ignored. - - The interactions between the identification fields you provide - and those identified in your lib/ssleay.conf are the same as if - you did an ordinary "ca -in infile -out outfile" -- that is, if - something is marked as required in the ssleay.conf file and it - isn't found in the -spkac file, the certificate won't be issued. - -- Now, you pick up the output from /tmp/cert and pass it back to - the Navigator prepending the Content-type string described earlier. - -- In order to run the ca command out of a CGI program, you must - provide a password to decrypt the CA's private key. You can - do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..." - I think there's a way to not encrypt the key file in the first - place, but I didn't see how to do that, so I made a small change - to the library that allows the password to be accepted from a pipe. - Either way is UTTERLY INSECURE and a real CA would never do that. - - [ You can use the 'ssleay rsa' command to remove the password - from the private key, or you can use the '-key' option to the - ca command to specify the decryption key on the command line - or use the -nodes option when generating the key. - ca will try to clear the command line version of the password - but for quite a few operating systems, this is not possible. - - eric ] - -So, what do you have to do to make use of this stuff to create an online -demo CA capability with SSLeay? - -1 Create an HTML form for your users. The form should contain - fields for all of the required or optional fields in ssleay.conf. - The form must contain a KEYGEN tag somewhere with at least a NAME - attribute. - -2 Create a CGI program to process the form input submitted by the - browser. The CGI program must URL-decode the variables and create - the file described above, containing subject identification info - as well as the SPKAC block. It should then run the the ca program - with the -spkac option. If it works (check the exit status), - return the new certificate with the appropriate MIME type. If not, - return the output of the ca command with MIME type "text/plain". - -3 Set up your web server to accept connections signed by your demo - CA. This probably involves obtaining the PEM-encoded CA certificate - (ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a - server database. See your server manual for instructions. - - -==== obj.doc ======================================================== - -The Object library. - -As part of my Crypto library, I found I required a method of identifying various -objects. These objects normally had 3 different values associated with -them, a short text name, a long (or lower case) text name, and an -ASN.1 Object Identifier (which is a sequence of numbers). -This library contains a static list of objects and functions to lookup -according to one type and to return the other types. - -To use these routines, 'Object.h' needs to be included. - -For each supported object, #define entries are defined as follows -#define SN_Algorithm "Algorithm" -#define LN_algorithm "algorithm" -#define NID_algorithm 38 -#define OBJ_algorithm 1L,3L,14L,3L,2L - -SN_ stands for short name. -LN_ stands for either long name or lowercase name. -NID_ stands for Numeric ID. I each object has a unique NID and this - should be used internally to identify objects. -OBJ_ stands for ASN.1 Object Identifier or ASN1_OBJECT as defined in the - ASN1 routines. These values are used in ASN1 encoding. - -The following functions are to be used to return pointers into a static -definition of these types. What this means is "don't try to free() any -pointers returned from these functions. - -ASN1_OBJECT *OBJ_nid2obj( -int n); - Return the ASN1_OBJECT that corresponds to a NID of n. - -char *OBJ_nid2ln( -int n); - Return the long/lower case name of the object represented by the - NID of n. - -char *OBJ_nid2sn( -int n); - Return the short name for the object represented by the NID of n. - -ASN1_OBJECT *OBJ_dup( -ASN1_OBJECT *o); - Duplicate and return a new ASN1_OBJECT that is the same as the - passed parameter. - -int OBJ_obj2nid( -ASN1_OBJECT *o); - Given ASN1_OBJECT o, return the NID that corresponds. - -int OBJ_ln2nid( -char *s); - Given the long/lower case name 's', return the NID of the object. - -int OBJ_sn2nid( -char *s); - Given the short name 's', return the NID of the object. - -char *OBJ_bsearch( -char *key, -char *base, -int num, -int size, -int (*cmp)()); - Since I have come across a few platforms that do not have the - bsearch() function, OBJ_bsearch is my version of that function. - Feel free to use this function, but you may as well just use the - normal system bsearch(3) if it is present. This version also - has tolerance of being passed NULL pointers. - -==== keys =========================================================== - -EVP_PKEY_DSA -EVP_PKEY_DSA2 -EVP_PKEY_DSA3 -EVP_PKEY_DSA4 - -EVP_PKEY_RSA -EVP_PKEY_RSA2 - -valid DSA pkey types - NID_dsa - NID_dsaWithSHA - NID_dsaWithSHA1 - NID_dsaWithSHA1_2 - -valid RSA pkey types - NID_rsaEncryption - NID_rsa - -NID_dsaWithSHA NID_dsaWithSHA DSA SHA -NID_dsa NID_dsaWithSHA1 DSA SHA1 -NID_md2 NID_md2WithRSAEncryption RSA-pkcs1 MD2 -NID_md5 NID_md5WithRSAEncryption RSA-pkcs1 MD5 -NID_mdc2 NID_mdc2WithRSA RSA-none MDC2 -NID_ripemd160 NID_ripemd160WithRSA RSA-pkcs1 RIPEMD160 -NID_sha NID_shaWithRSAEncryption RSA-pkcs1 SHA -NID_sha1 NID_sha1WithRSAEncryption RSA-pkcs1 SHA1 - -==== rand.doc ======================================================== - -My Random number library. - -These routines can be used to generate pseudo random numbers and can be -used to 'seed' the pseudo random number generator (RNG). The RNG make no -effort to reproduce the same random number stream with each execution. -Various other routines in the SSLeay library 'seed' the RNG when suitable -'random' input data is available. Read the section at the end for details -on the design of the RNG. - -void RAND_bytes( -unsigned char *buf, -int num); - This routine puts 'num' random bytes into 'buf'. One should make - sure RAND_seed() has been called before using this routine. - -void RAND_seed( -unsigned char *buf, -int num); - This routine adds more 'seed' data the RNG state. 'num' bytes - are added to the RNG state, they are taken from 'buf'. This - routine can be called with sensitive data such as user entered - passwords. This sensitive data is in no way recoverable from - the RAND library routines or state. Try to pass as much data - from 'random' sources as possible into the RNG via this function. - Also strongly consider using the RAND_load_file() and - RAND_write_file() routines. - -void RAND_cleanup(); - When a program has finished with the RAND library, if it so - desires, it can 'zero' all RNG state. - -The following 3 routines are convenience routines that can be used to -'save' and 'restore' data from/to the RNG and it's state. -Since the more 'random' data that is feed as seed data the better, why not -keep it around between executions of the program? Of course the -application should pass more 'random' data in via RAND_seed() and -make sure no-one can read the 'random' data file. - -char *RAND_file_name( -char *buf, -int size); - This routine returns a 'default' name for the location of a 'rand' - file. The 'rand' file should keep a sequence of random bytes used - to initialise the RNG. The filename is put in 'buf'. Buf is 'size' - bytes long. Buf is returned if things go well, if they do not, - NULL is returned. The 'rand' file name is generated in the - following way. First, if there is a 'RANDFILE' environment - variable, it is returned. Second, if there is a 'HOME' environment - variable, $HOME/.rand is returned. Third, NULL is returned. NULL - is also returned if a buf would overflow. - -int RAND_load_file( -char *file, -long number); - This function 'adds' the 'file' into the RNG state. It does this by - doing a RAND_seed() on the value returned from a stat() system call - on the file and if 'number' is non-zero, upto 'number' bytes read - from the file. The number of bytes passed to RAND_seed() is returned. - -int RAND_write_file( -char *file), - RAND_write_file() writes N random bytes to the file 'file', where - N is the size of the internal RND state (currently 1k). - This is a suitable method of saving RNG state for reloading via - RAND_load_file(). - -What follows is a description of this RNG and a description of the rational -behind it's design. - -It should be noted that this RNG is intended to be used to generate -'random' keys for various ciphers including generation of DH and RSA keys. - -It should also be noted that I have just created a system that I am happy with. -It may be overkill but that does not worry me. I have not spent that much -time on this algorithm so if there are glaring errors, please let me know. -Speed has not been a consideration in the design of these routines. - -First up I will state the things I believe I need for a good RNG. -1) A good hashing algorithm to mix things up and to convert the RNG 'state' - to random numbers. -2) An initial source of random 'state'. -3) The state should be very large. If the RNG is being used to generate - 4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). - If your RNG state only has 128 bits, you are obviously limiting the - search space to 128 bits, not 2048. I'm probably getting a little - carried away on this last point but it does indicate that it may not be - a bad idea to keep quite a lot of RNG state. It should be easier to - break a cipher than guess the RNG seed data. -4) Any RNG seed data should influence all subsequent random numbers - generated. This implies that any random seed data entered will have - an influence on all subsequent random numbers generated. -5) When using data to seed the RNG state, the data used should not be - extractable from the RNG state. I believe this should be a - requirement because one possible source of 'secret' semi random - data would be a private key or a password. This data must - not be disclosed by either subsequent random numbers or a - 'core' dump left by a program crash. -6) Given the same initial 'state', 2 systems should deviate in their RNG state - (and hence the random numbers generated) over time if at all possible. -7) Given the random number output stream, it should not be possible to determine - the RNG state or the next random number. - - -The algorithm is as follows. - -There is global state made up of a 1023 byte buffer (the 'state'), a -working message digest ('md') and a counter ('count'). - -Whenever seed data is added, it is inserted into the 'state' as -follows. - The input is chopped up into units of 16 bytes (or less for - the last block). Each of these blocks is run through the MD5 - message digest. The data passed to the MD5 digest is the - current 'md', the same number of bytes from the 'state' - (the location determined by in incremented looping index) as - the current 'block' and the new key data 'block'. The result - of this is kept in 'md' and also xored into the 'state' at the - same locations that were used as input into the MD5. - I believe this system addresses points 1 (MD5), 3 (the 'state'), - 4 (via the 'md'), 5 (by the use of MD5 and xor). - -When bytes are extracted from the RNG, the following process is used. -For each group of 8 bytes (or less), we do the following, - Input into MD5, the top 8 bytes from 'md', the byte that are - to be overwritten by the random bytes and bytes from the - 'state' (incrementing looping index). From this digest output - (which is kept in 'md'), the top (upto) 8 bytes are - returned to the caller and the bottom (upto) 8 bytes are xored - into the 'state'. - Finally, after we have finished 'generation' random bytes for the - called, 'count' (which is incremented) and 'md' are fed into MD5 and - the results are kept in 'md'. - I believe the above addressed points 1 (use of MD5), 6 (by - hashing into the 'state' the 'old' data from the caller that - is about to be overwritten) and 7 (by not using the 8 bytes - given to the caller to update the 'state', but they are used - to update 'md'). - -So of the points raised, only 2 is not addressed, but sources of -random data will always be a problem. - - -==== rc2.doc ======================================================== - -The RC2 library. - -RC2 is a block cipher that operates on 64bit (8 byte) quantities. It -uses variable size key, but 128bit (16 byte) key would normally be considered -good. It can be used in all the modes that DES can be used. This -library implements the ecb, cbc, cfb64, ofb64 modes. - -I have implemented this library from an article posted to sci.crypt on -11-Feb-1996. I personally don't know how far to trust the RC2 cipher. -While it is capable of having a key of any size, not much reseach has -publically been done on it at this point in time (Apr-1996) -since the cipher has only been public for a few months :-) -It is of a similar speed to DES and IDEA, so unless it is required for -meeting some standard (SSLv2, perhaps S/MIME), it would probably be advisable -to stick to IDEA, or for the paranoid, Tripple DES. - -Mind you, having said all that, I should mention that I just read alot and -implement ciphers, I'm a 'babe in the woods' when it comes to evaluating -ciphers :-). - -For all calls that have an 'input' and 'output' variables, they can be the -same. - -This library requires the inclusion of 'rc2.h'. - -All of the encryption functions take what is called an RC2_KEY as an -argument. An RC2_KEY is an expanded form of the RC2 key. -For all modes of the RC2 algorithm, the RC2_KEY used for -decryption is the same one that was used for encryption. - -The define RC2_ENCRYPT is passed to specify encryption for the functions -that require an encryption/decryption flag. RC2_DECRYPT is passed to -specify decryption. - -Please note that any of the encryption modes specified in my DES library -could be used with RC2. I have only implemented ecb, cbc, cfb64 and -ofb64 for the following reasons. -- ecb is the basic RC2 encryption. -- cbc is the normal 'chaining' form for block ciphers. -- cfb64 can be used to encrypt single characters, therefore input and output - do not need to be a multiple of 8. -- ofb64 is similar to cfb64 but is more like a stream cipher, not as - secure (not cipher feedback) but it does not have an encrypt/decrypt mode. -- If you want triple RC2, thats 384 bits of key and you must be totally - obsessed with security. Still, if you want it, it is simple enough to - copy the function from the DES library and change the des_encrypt to - RC2_encrypt; an exercise left for the paranoid reader :-). - -The functions are as follows: - -void RC2_set_key( -RC2_KEY *ks; -int len; -unsigned char *key; -int bits; - RC2_set_key converts an 'len' byte key into a RC2_KEY. - A 'ks' is an expanded form of the 'key' which is used to - perform actual encryption. It can be regenerated from the RC2 key - so it only needs to be kept when encryption or decryption is about - to occur. Don't save or pass around RC2_KEY's since they - are CPU architecture dependent, 'key's are not. RC2 is an - interesting cipher in that it can be used with a variable length - key. 'len' is the length of 'key' to be used as the key. - A 'len' of 16 is recomended. The 'bits' argument is an - interesting addition which I only found out about in Aug 96. - BSAFE uses this parameter to 'limit' the number of bits used - for the key. To use the 'key' unmodified, set bits to 1024. - This is what old versions of my RC2 library did (SSLeay 0.6.3). - RSAs BSAFE library sets this parameter to be 128 if 128 bit - keys are being used. So to be compatable with BSAFE, set it - to 128, if you don't want to reduce RC2's key length, leave it - at 1024. - -void RC2_encrypt( -unsigned long *data, -RC2_KEY *key, -int encrypt); - This is the RC2 encryption function that gets called by just about - every other RC2 routine in the library. You should not use this - function except to implement 'modes' of RC2. I say this because the - functions that call this routine do the conversion from 'char *' to - long, and this needs to be done to make sure 'non-aligned' memory - access do not occur. - Data is a pointer to 2 unsigned long's and key is the - RC2_KEY to use. Encryption or decryption is indicated by 'encrypt'. - which can have the values RC2_ENCRYPT or RC2_DECRYPT. - -void RC2_ecb_encrypt( -unsigned char *in, -unsigned char *out, -RC2_KEY *key, -int encrypt); - This is the basic Electronic Code Book form of RC2 (in DES this - mode is called Electronic Code Book so I'm going to use the term - for rc2 as well. - Input is encrypted into output using the key represented by - key. Depending on the encrypt, encryption or - decryption occurs. Input is 8 bytes long and output is 8 bytes. - -void RC2_cbc_encrypt( -unsigned char *in, -unsigned char *out, -long length, -RC2_KEY *ks, -unsigned char *ivec, -int encrypt); - This routine implements RC2 in Cipher Block Chaining mode. - Input, which should be a multiple of 8 bytes is encrypted - (or decrypted) to output which will also be a multiple of 8 bytes. - The number of bytes is in length (and from what I've said above, - should be a multiple of 8). If length is not a multiple of 8, bad - things will probably happen. ivec is the initialisation vector. - This function updates iv after each call so that it can be passed to - the next call to RC2_cbc_encrypt(). - -void RC2_cfb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -RC2_KEY *schedule, -unsigned char *ivec, -int *num, -int encrypt); - This is one of the more useful functions in this RC2 library, it - implements CFB mode of RC2 with 64bit feedback. - This allows you to encrypt an arbitrary number of bytes, - you do not require 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. - 'Encrypt' is used to indicate encryption or decryption. - CFB64 mode operates by using the cipher to generate a stream - of bytes which is used to encrypt the plain text. - The cipher text is then encrypted to generate the next 64 bits to - be xored (incrementally) with the next 64 bits of plain - text. As can be seen from this, to encrypt or decrypt, - the same 'cipher stream' needs to be generated but the way the next - block of data is gathered for encryption is different for - encryption and decryption. - -void RC2_ofb64_encrypt( -unsigned char *in, -unsigned char *out, -long length, -RC2_KEY *schedule, -unsigned char *ivec, -int *num); - This functions implements OFB mode of RC2 with 64bit feedback. - This allows you to encrypt an arbitrary number of bytes, - you do not require 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. - This is in effect a stream cipher, there is no encryption or - decryption mode. - -For reading passwords, I suggest using des_read_pw_string() from my DES library. -To generate a password from a text string, I suggest using MD5 (or MD2) to -produce a 16 byte message digest that can then be passed directly to -RC2_set_key(). - -===== -For more information about the specific RC2 modes in this library -(ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the -documentation on my DES library. What is said about DES is directly -applicable for RC2. - - -==== rc4.doc ======================================================== - -The RC4 library. -RC4 is a stream cipher that operates on a byte stream. It can be used with -any length key but I would recommend normally using 16 bytes. - -This library requires the inclusion of 'rc4.h'. - -The RC4 encryption function takes what is called an RC4_KEY as an argument. -The RC4_KEY is generated by the RC4_set_key function from the key bytes. - -RC4, being a stream cipher, does not have an encryption or decryption mode. -It produces a stream of bytes that the input stream is xor'ed against and -so decryption is just a case of 'encrypting' again with the same key. - -I have only put in one 'mode' for RC4 which is the normal one. This means -there is no initialisation vector and there is no feedback of the cipher -text into the cipher. This implies that you should not ever use the -same key twice if you can help it. If you do, you leave yourself open to -known plain text attacks; if you know the plain text and -corresponding cipher text in one message, all messages that used the same -key can have the cipher text decoded for the corresponding positions in the -cipher stream. - -The main positive feature of RC4 is that it is a very fast cipher; about 4 -times faster that DES. This makes it ideally suited to protocols where the -key is randomly chosen, like SSL. - -The functions are as follows: - -void RC4_set_key( -RC4_KEY *key; -int len; -unsigned char *data); - This function initialises the RC4_KEY structure with the key passed - in 'data', which is 'len' bytes long. The key data can be any - length but 16 bytes seems to be a good number. - -void RC4( -RC4_KEY *key; -unsigned long len; -unsigned char *in; -unsigned char *out); - Do the actual RC4 encryption/decryption. Using the 'key', 'len' - bytes are transformed from 'in' to 'out'. As mentioned above, - decryption is the operation as encryption. - -==== ref.doc ======================================================== - -I have lots more references etc, and will update this list in the future, -30 Aug 1996 - eay - - -SSL The SSL Protocol - from Netscapes. - -RC4 Newsgroups: sci.crypt - From: sterndark@netcom.com (David Sterndark) - Subject: RC4 Algorithm revealed. - Message-ID: <sternCvKL4B.Hyy@netcom.com> - -RC2 Newsgroups: sci.crypt - From: pgut01@cs.auckland.ac.nz (Peter Gutmann) - Subject: Specification for Ron Rivests Cipher No.2 - Message-ID: <4fk39f$f70@net.auckland.ac.nz> - -MD2 RFC1319 The MD2 Message-Digest Algorithm -MD5 RFC1321 The MD5 Message-Digest Algorithm - -X509 Certificates - RFC1421 Privacy Enhancement for Internet Electronic Mail: Part I - RFC1422 Privacy Enhancement for Internet Electronic Mail: Part II - RFC1423 Privacy Enhancement for Internet Electronic Mail: Part III - RFC1424 Privacy Enhancement for Internet Electronic Mail: Part IV - -RSA and various standard encoding - PKCS#1 RSA Encryption Standard - PKCS#5 Password-Based Encryption Standard - PKCS#7 Cryptographic Message Syntax Standard - A Layman's Guide to a Subset of ASN.1, BER, and DER - An Overview of the PKCS Standards - Some Examples of the PKCS Standards - -IDEA Chapter 3 The Block Cipher IDEA - -RSA, prime number generation and bignum algorithms - Introduction To Algorithms, - Thomas Cormen, Charles Leiserson, Ronald Rivest, - Section 29 Arithmetic Circuits - Section 33 Number-Theoretic Algorithms - -Fast Private Key algorithm - Fast Decipherment Algorithm for RSA Public-Key Cryptosystem - J.-J. Quisquater and C. Couvreur, Electronics Letters, - 14th October 1982, Vol. 18 No. 21 - -Prime number generation and bignum algorithms. - PGP-2.3a - -==== rsa.doc ======================================================== - -The RSA encryption and utility routines. - -The RSA routines are built on top of a big number library (the BN library). -There are support routines in the X509 library for loading and manipulating -the various objects in the RSA library. When errors are returned, read -about the ERR library for how to access the error codes. - -All RSA encryption is done according to the PKCS-1 standard which is -compatible with PEM and RSAref. This means that any values being encrypted -must be less than the size of the modulus in bytes, minus 10, bytes long. - -This library uses RAND_bytes()() for it's random data, make sure to feed -RAND_seed() with lots of interesting and varied data before using these -routines. - -The RSA library has one specific data type, the RSA structure. -It is composed of 8 BIGNUM variables (see the BN library for details) and -can hold either a private RSA key or a public RSA key. -Some RSA libraries have different structures for public and private keys, I -don't. For my libraries, a public key is determined by the fact that the -RSA->d value is NULL. These routines will operate on any size RSA keys. -While I'm sure 4096 bit keys are very very secure, they take a lot longer -to process that 1024 bit keys :-). - -The function in the RSA library are as follows. - -RSA *RSA_new(); - This function creates a new RSA object. The sub-fields of the RSA - type are also malloced so you should always use this routine to - create RSA variables. - -void RSA_free( -RSA *rsa); - This function 'frees' an RSA structure. This routine should always - be used to free the RSA structure since it will also 'free' any - sub-fields of the RSA type that need freeing. - -int RSA_size( -RSA *rsa); - This function returns the size of the RSA modulus in bytes. Why do - I need this you may ask, well the reason is that when you encrypt - with RSA, the output string will be the size of the RSA modulus. - So the output for the RSA_encrypt and the input for the RSA_decrypt - routines need to be RSA_size() bytes long, because this is how many - bytes are expected. - -For the following 4 RSA encryption routines, it should be noted that -RSA_private_decrypt() should be used on the output from -RSA_public_encrypt() and RSA_public_decrypt() should be used on -the output from RSA_private_encrypt(). - -int RSA_public_encrypt( -int from_len; -unsigned char *from -unsigned char *to -RSA *rsa); - This function implements RSA public encryption, the rsa variable - should be a public key (but can be a private key). 'from_len' - bytes taken from 'from' and encrypted and put into 'to'. 'to' needs - to be at least RSA_size(rsa) bytes long. The number of bytes - written into 'to' is returned. -1 is returned on an error. The - operation performed is - to = from^rsa->e mod rsa->n. - -int RSA_private_encrypt( -int from_len; -unsigned char *from -unsigned char *to -RSA *rsa); - This function implements RSA private encryption, the rsa variable - should be a private key. 'from_len' bytes taken from - 'from' and encrypted and put into 'to'. 'to' needs - to be at least RSA_size(rsa) bytes long. The number of bytes - written into 'to' is returned. -1 is returned on an error. The - operation performed is - to = from^rsa->d mod rsa->n. - -int RSA_public_decrypt( -int from_len; -unsigned char *from -unsigned char *to -RSA *rsa); - This function implements RSA public decryption, the rsa variable - should be a public key (but can be a private key). 'from_len' - bytes are taken from 'from' and decrypted. The decrypted data is - put into 'to'. The number of bytes encrypted is returned. -1 is - returned to indicate an error. The operation performed is - to = from^rsa->e mod rsa->n. - -int RSA_private_decrypt( -int from_len; -unsigned char *from -unsigned char *to -RSA *rsa); - This function implements RSA private decryption, the rsa variable - should be a private key. 'from_len' bytes are taken - from 'from' and decrypted. The decrypted data is - put into 'to'. The number of bytes encrypted is returned. -1 is - returned to indicate an error. The operation performed is - to = from^rsa->d mod rsa->n. - -int RSA_mod_exp( -BIGNUM *n; -BIGNUM *p; -RSA *rsa); - Normally you will never use this routine. - This is really an internal function which is called by - RSA_private_encrypt() and RSA_private_decrypt(). It performs - n=n^p mod rsa->n except that it uses the 5 extra variables in the - RSA structure to make this more efficient. - -RSA *RSA_generate_key( -int bits; -unsigned long e; -void (*callback)(); -char *cb_arg; - This routine is used to generate RSA private keys. It takes - quite a period of time to run and should only be used to - generate initial private keys that should then be stored - for later use. The passed callback function - will be called periodically so that feedback can be given - as to how this function is progressing. - 'bits' is the length desired for the modulus, so it would be 1024 - to generate a 1024 bit private key. - 'e' is the value to use for the public exponent 'e'. Traditionally - it is set to either 3 or 0x10001. - The callback function (if not NULL) is called in the following - situations. - when we have generated a suspected prime number to test, - callback(0,num1++,cb_arg). When it passes a prime number test, - callback(1,num2++,cb_arg). When it is rejected as one of - the 2 primes required due to gcd(prime,e value) != 0, - callback(2,num3++,cb_arg). When finally accepted as one - of the 2 primes, callback(3,num4++,cb_arg). - - -==== rsaref.doc ======================================================== - -This package can be compiled to use the RSAref library. -This library is not allowed outside of the USA but inside the USA it is -claimed by RSA to be the only RSA public key library that can be used -besides BSAFE.. - -There are 2 files, rsaref/rsaref.c and rsaref/rsaref.h that contain the glue -code to use RSAref. These files were written by looking at the PGP -source code and seeing which routines it used to access RSAref. -I have also been sent by some-one a copy of the RSAref header file that -contains the library error codes. - -[ Jun 1996 update - I have recently gotten hold of RSAref 2.0 from - South Africa and have been doing some performace tests. ] - -They have now been tested against the recently announced RSAEURO -library. - -There are 2 ways to use SSLeay and RSAref. First, to build so that -the programs must be linked with RSAref, add '-DRSAref' to CFLAG in the top -level makefile and -lrsaref (or where ever you are keeping RSAref) to -EX_LIBS. - -To build a makefile via util/mk1mf.pl to do this, use the 'rsaref' option. - -The second method is to build as per normal and link applications with -the RSAglue library. The correct library order would be -cc -o cmd cmd.o -lssl -lRSAglue -lcrypto -lrsaref -ldes -The RSAglue library is built in the rsa directory and is NOT -automatically installed. - -Be warned that the RSAEURO library, that is claimed to be compatible -with RSAref contains a different value for the maximum number of bits -supported. This changes structure sizes and so if you are using -RSAEURO, change the value of RSAref_MAX_BITS in rsa/rsaref.h - - -==== s_mult.doc ======================================================== - -s_mult is a test program I hacked up on a Sunday for testing non-blocking -IO. It has a select loop at it's centre that handles multiple readers -and writers. - -Try the following command -ssleay s_mult -echo -nbio -ssl -v -echo - sends any sent text back to the sender -nbio - turns on non-blocking IO -ssl - accept SSL connections, default is normal text -v - print lots - type Q<cr> to quit - -In another window, run the following -ssleay s_client -pause </etc/termcap - -The pause option puts in a 1 second pause in each read(2)/write(2) call -so the other end will have read()s fail. - -==== session.doc ======================================================== - -I have just checked over and re-worked the session stuff. -The following brief example will ignore all setup information to do with -authentication. - -Things operate as follows. - -The SSL environment has a 'context', a SSL_CTX structure. This holds the -cached SSL_SESSIONS (which can be reused) and the certificate lookup -information. Each SSL structure needs to be associated with a SSL_CTX. -Normally only one SSL_CTX structure is needed per program. - -SSL_CTX *SSL_CTX_new(void ); -void SSL_CTX_free(SSL_CTX *); -These 2 functions create and destroy SSL_CTX structures - -The SSL_CTX has a session_cache_mode which is by default, -in SSL_SESS_CACHE_SERVER mode. What this means is that the library -will automatically add new session-id's to the cache upon successful -SSL_accept() calls. -If SSL_SESS_CACHE_CLIENT is set, then client certificates are also added -to the cache. -SSL_set_session_cache_mode(ctx,mode) will set the 'mode' and -SSL_get_session_cache_mode(ctx) will get the cache 'mode'. -The modes can be -SSL_SESS_CACHE_OFF - no caching -SSL_SESS_CACHE_CLIENT - only SSL_connect() -SSL_SESS_CACHE_SERVER - only SSL_accept() -SSL_SESS_NO_CACHE_BOTH - Either SSL_accept() or SSL_connect(). -If SSL_SESS_CACHE_NO_AUTO_CLEAR is set, old timed out sessions are -not automatically removed each 255, SSL_connect()s or SSL_accept()s. - -By default, upon every 255 successful SSL_connect() or SSL_accept()s, -the cache is flush. Please note that this could be expensive on -a heavily loaded SSL server, in which case, turn this off and -clear the cache of old entries 'manually' (with one of the functions -listed below) every few hours. Perhaps I should up this number, it is hard -to say. Remember, the '255' new calls is just a mechanism to get called -every now and then, in theory at most 255 new session-id's will have been -added but if 100 are added every minute, you would still have -500 in the cache before any would start being flushed (assuming a 3 minute -timeout).. - -int SSL_CTX_sess_hits(SSL_CTX *ctx); -int SSL_CTX_sess_misses(SSL_CTX *ctx); -int SSL_CTX_sess_timeouts(SSL_CTX *ctx); -These 3 functions return statistics about the SSL_CTX. These 3 are the -number of session id reuses. hits is the number of reuses, misses are the -number of lookups that failed, and timeouts is the number of cached -entries ignored because they had timeouted. - -ctx->new_session_cb is a function pointer to a function of type -int new_session_callback(SSL *ssl,SSL_SESSION *new); -This function, if set in the SSL_CTX structure is called whenever a new -SSL_SESSION is added to the cache. If the callback returns non-zero, it -means that the application will have to do a SSL_SESSION_free() -on the structure (this is -to do with the cache keeping the reference counts correct, without the -application needing to know about it. -The 'active' parameter is the current SSL session for which this connection -was created. - -void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx,int (*cb)()); -to set the callback, -int (*cb)() SSL_CTX_sess_get_new_cb(SSL_CTX *ctx) -to get the callback. - -If the 'get session' callback is set, when a session id is looked up and -it is not in the session-id cache, this callback is called. The callback is -of the form -SSL_SESSION *get_session_callback(unsigned char *sess_id,int sess_id_len, - int *copy); - -The get_session_callback is intended to return null if no session id is found. -The reference count on the SSL_SESSION in incremented by the SSL library, -if copy is 1. Otherwise, the reference count is not modified. - -void SSL_CTX_sess_set_get_cb(ctx,cb) sets the callback and -int (*cb)()SSL_CTX_sess_get_get_cb(ctx) returns the callback. - -These callbacks are basically intended to be used by processes to -send their session-id's to other processes. I currently have not implemented -non-blocking semantics for these callbacks, it is upto the application -to make the callbacks efficient if they require blocking (perhaps -by 'saving' them and then 'posting them' when control returns from -the SSL_accept(). - -LHASH *SSL_CTX_sessions(SSL_CTX *ctx) -This returns the session cache. The lhash strucutre can be accessed for -statistics about the cache. - -void lh_stats(LHASH *lh, FILE *out); -void lh_node_stats(LHASH *lh, FILE *out); -void lh_node_usage_stats(LHASH *lh, FILE *out); - -can be used to print details about it's activity and current state. -You can also delve directly into the lhash structure for 14 different -counters that are kept against the structure. When I wrote the lhash library, -I was interested in gathering statistics :-). -Have a read of doc/lhash.doc in the SSLeay distribution area for more details -on the lhash library. - -Now as mentioned ealier, when a SSL is created, it needs a SSL_CTX. -SSL * SSL_new(SSL_CTX *); - -This stores a session. A session is secret information shared between 2 -SSL contexts. It will only be created if both ends of the connection have -authenticated their peer to their satisfaction. It basically contains -the information required to use a particular secret key cipher. - -To retrieve the SSL_CTX being used by a SSL, -SSL_CTX *SSL_get_SSL_CTX(SSL *s); - -Now when a SSL session is established between to programs, the 'session' -information that is cached in the SSL_CTX can me manipulated by the -following functions. -int SSL_set_session(SSL *s, SSL_SESSION *session); -This will set the SSL_SESSION to use for the next SSL_connect(). If you use -this function on an already 'open' established SSL connection, 'bad things -will happen'. This function is meaning-less when used on a ssl strucutre -that is just about to be used in a SSL_accept() call since the -SSL_accept() will either create a new session or retrieve one from the -cache. - -SSL_SESSION *SSL_get_session(SSL *s); -This will return the SSL_SESSION for the current SSL, NULL if there is -no session associated with the SSL structure. - -The SSL sessions are kept in the SSL_CTX in a hash table, to remove a -session -void SSL_CTX_remove_session(SSL_CTX *,SSL_SESSION *c); -and to add one -int SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c); -SSL_CTX_add_session() returns 1 if the session was already in the cache (so it -was not added). -Whenever a new session is created via SSL_connect()/SSL_accept(), -they are automatically added to the cache, depending on the session_cache_mode -settings. SSL_set_session() -does not add it to the cache. Just call SSL_CTX_add_session() if you do want the -session added. For a 'client' this would not normally be the case. -SSL_CTX_add_session() is not normally ever used, except for doing 'evil' things -which the next 2 funtions help you do. - -int i2d_SSL_SESSION(SSL_SESSION *in,unsigned char **pp); -SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a,unsigned char **pp,long length); -These 2 functions are in the standard ASN1 library form and can be used to -load and save to a byte format, the SSL_SESSION structure. -With these functions, you can save and read these structures to a files or -arbitary byte string. -The PEM_write_SSL_SESSION(fp,x) and PEM_read_SSL_SESSION(fp,x,cb) will -write to a file pointer in base64 encoding. - -What you can do with this, is pass session information between separate -processes. Please note, that you will probably also need to modify the -timeout information on the SSL_SESSIONs. - -long SSL_get_time(SSL_SESSION *s) -will return the 'time' that the session -was loaded. The timeout is relative to this time. This information is -saved when the SSL_SESSION is converted to binarary but it is stored -in as a unix long, which is rather OS dependant, but easy to convert back. - -long SSL_set_time(SSL_SESSION *s,long t) will set the above mentioned time. -The time value is just the value returned from time(3), and should really -be defined by be to be time_t. - -long SSL_get_timeout(SSL_SESSION *s); -long SSL_set_timeout(SSL_SESSION *s,long t); -These 2 retrieve and set the timeout which is just a number of secconds -from the 'SSL_get_time()' value. When this time period has elapesed, -the session will no longer be in the cache (well it will actually be removed -the next time it is attempted to be retrieved, so you could 'bump' -the timeout so it remains valid). -The 'time' and 'timeout' are set on a session when it is created, not reset -each time it is reused. If you did wish to 'bump it', just after establishing -a connection, do a -SSL_set_time(ssl,time(NULL)); - -You can also use -SSL_CTX_set_timeout(SSL_CTX *ctx,unsigned long t) and -SSL_CTX_get_timeout(SSL_CTX *ctx) to manipulate the default timeouts for -all SSL connections created against a SSL_CTX. If you set a timeout in -an SSL_CTX, all new SSL's created will inherit the timeout. It can be over -written by the SSL_set_timeout(SSL *s,unsigned long t) function call. -If you 'set' the timeout back to 0, the system default will be used. - -SSL_SESSION *SSL_SESSION_new(); -void SSL_SESSION_free(SSL_SESSION *ses); -These 2 functions are used to create and dispose of SSL_SESSION functions. -You should not ever normally need to use them unless you are using -i2d_SSL_SESSION() and/or d2i_SSL_SESSION(). If you 'load' a SSL_SESSION -via d2i_SSL_SESSION(), you will need to SSL_SESSION_free() it. -Both SSL_set_session() and SSL_CTX_add_session() will 'take copies' of the -structure (via reference counts) when it is passed to them. - -SSL_CTX_flush_sessions(ctx,time); -The first function will clear all sessions from the cache, which have expired -relative to 'time' (which could just be time(NULL)). - -SSL_CTX_flush_sessions(ctx,0); -This is a special case that clears everything. - -As a final comment, a 'session' is not enough to establish a new -connection. If a session has timed out, a certificate and private key -need to have been associated with the SSL structure. -SSL_copy_session_id(SSL *to,SSL *from); will copy not only the session -strucutre but also the private key and certificate associated with -'from'. - -EXAMPLES. - -So lets play at being a weird SSL server. - -/* setup a context */ -ctx=SSL_CTX_new(); - -/* Lets load some session from binary into the cache, why one would do - * this is not toally clear, but passing between programs does make sense - * Perhaps you are using 4096 bit keys and are happy to keep them - * valid for a week, to avoid the RSA overhead of 15 seconds, I'm not toally - * sure, perhaps this is a process called from an SSL inetd and this is being - * passed to the application. */ -session=d2i_SSL_SESSION(....) -SSL_CTX_add_session(ctx,session); - -/* Lets even add a session from a file */ -session=PEM_read_SSL_SESSION(....) -SSL_CTX_add_session(ctx,session); - -/* create a new SSL structure */ -ssl=SSL_new(ctx); - -/* At this point we want to be able to 'create' new session if - * required, so we need a certificate and RSAkey. */ -SSL_use_RSAPrivateKey_file(ssl,...) -SSL_use_certificate_file(ssl,...) - -/* Now since we are a server, it make little sence to load a session against - * the ssl strucutre since a SSL_accept() will either create a new session or - * grab an existing one from the cache. */ - -/* grab a socket descriptor */ -fd=accept(...); - -/* associated it with the ssl strucutre */ -SSL_set_fd(ssl,fd); - -SSL_accept(ssl); /* 'do' SSL using out cert and RSA key */ - -/* Lets print out the session details or lets save it to a file, - * perhaps with a secret key cipher, so that we can pass it to the FBI - * when they want to decode the session :-). While we have RSA - * this does not matter much but when I do SSLv3, this will allow a mechanism - * for the server/client to record the information needed to decode - * the traffic that went over the wire, even when using Diffie-Hellman */ -PEM_write_SSL_SESSION(SSL_get_session(ssl),stdout,....) - -Lets 'connect' back to the caller using the same session id. - -ssl2=SSL_new(ctx); -fd2=connect(them); -SSL_set_fd(ssl2,fd2); -SSL_set_session(ssl2,SSL_get_session(ssl)); -SSL_connect(ssl2); - -/* what the hell, lets accept no more connections using this session */ -SSL_CTX_remove_session(SSL_get_SSL_CTX(ssl),SSL_get_session(ssl)); - -/* we could have just as easily used ssl2 since they both are using the - * same session. - * You will note that both ssl and ssl2 are still using the session, and - * the SSL_SESSION structure will be free()ed when both ssl and ssl2 - * finish using the session. Also note that you could continue to initiate - * connections using this session by doing SSL_get_session(ssl) to get the - * existing session, but SSL_accept() will not be able to find it to - * use for incoming connections. - * Of corse, the session will timeout at the far end and it will no - * longer be accepted after a while. The time and timeout are ignored except - * by SSL_accept(). */ - -/* Since we have had our server running for 10 weeks, and memory is getting - * short, perhaps we should clear the session cache to remove those - * 100000 session entries that have expired. Some may consider this - * a memory leak :-) */ - -SSL_CTX_flush_sessions(ctx,time(NULL)); - -/* Ok, after a bit more time we wish to flush all sessions from the cache - * so that all new connections will be authenticated and incure the - * public key operation overhead */ - -SSL_CTX_flush_sessions(ctx,0); - -/* As a final note, to copy everything to do with a SSL, use */ -SSL_copy_session_id(SSL *to,SSL *from); -/* as this also copies the certificate and RSA key so new session can - * be established using the same details */ - - -==== sha.doc ======================================================== - -The SHA (Secure Hash Algorithm) library. -SHA is a message digest algorithm that can be used to condense an arbitrary -length message down to a 20 byte hash. The functions all need to be passed -a SHA_CTX which is used to hold the SHA context during multiple SHA_Update() -function calls. The normal method of use for this library is as follows -This library contains both SHA and SHA-1 digest algorithms. SHA-1 is -an update to SHA (which should really be called SHA-0 now) which -tweaks the algorithm slightly. The SHA-1 algorithm is used by simply -using SHA1_Init(), SHA1_Update(), SHA1_Final() and SHA1() instead of the -SHA*() calls - -SHA_Init(...); -SHA_Update(...); -... -SHA_Update(...); -SHA_Final(...); - -This library requires the inclusion of 'sha.h'. - -The functions are as follows: - -void SHA_Init( -SHA_CTX *c); - This function needs to be called to initiate a SHA_CTX structure for - use. - -void SHA_Update( -SHA_CTX *c; -unsigned char *data; -unsigned long len); - This updates the message digest context being generated with 'len' - bytes from the 'data' pointer. The number of bytes can be any - length. - -void SHA_Final( -unsigned char *md; -SHA_CTX *c; - This function is called when a message digest of the data digested - with SHA_Update() is wanted. The message digest is put in the 'md' - array and is SHA_DIGEST_LENGTH (20) bytes long. - -unsigned char *SHA( -unsigned char *d; -unsigned long n; -unsigned char *md; - This function performs a SHA_Init(), followed by a SHA_Update() - followed by a SHA_Final() (using a local SHA_CTX). - The resulting digest is put into 'md' if it is not NULL. - Regardless of the value of 'md', the message - digest is returned from the function. If 'md' was NULL, the message - digest returned is being stored in a static structure. - - -==== speed.doc ======================================================== - -To get an idea of the performance of this library, use -ssleay speed - -perl util/sp-diff.pl file1 file2 - -will print out the relative differences between the 2 files which are -expected to be the output from the speed program. - -The performace of the library is very dependant on the Compiler -quality and various flags used to build. - ---- - -These are some numbers I did comparing RSAref and SSLeay on a Pentium 100. -[ These numbers are all out of date, as of SSL - 0.6.1 the RSA -operations are about 2 times faster, so check the version number ] - -RSA performance. - -SSLeay 0.6.0 -Pentium 100, 32meg, Windows NT Workstation 3.51 -linux - gcc v 2.7.0 -O3 -fomit-frame-pointer -m486 -and -Windows NT - Windows NT 3.51 - Visual C++ 4.1 - 586 code + 32bit assember -Windows 3.1 - Windows NT 3.51 - Visual C++ 1.52c - 286 code + 32bit assember -NT Dos Shell- Windows NT 3.51 - Visual C++ 1.52c - 286 code + 16bit assember - -Times are how long it takes to do an RSA private key operation. - - 512bits 1024bits -------------------------------- -SSLeay NT dll 0.042s 0.202s see above -SSLeay linux 0.046s 0.218s Assember inner loops (normal build) -SSLeay linux 0.067s 0.380s Pure C code with BN_LLONG defined -SSLeay W3.1 dll 0.108s 0.478s see above -SSLeay linux 0.109s 0.713s C without BN_LLONG. -RSAref2.0 linux 0.149s 0.936s -SSLeay MS-DOS 0.197s 1.049s see above - -486DX66, 32meg, Windows NT Server 3.51 - 512bits 1024bits -------------------------------- -SSLeay NT dll 0.084s 0.495s <- SSLeay 0.6.3 -SSLeay NT dll 0.154s 0.882s -SSLeay W3.1 dll 0.335s 1.538s -SSLeay MS-DOS 0.490s 2.790s - -What I find cute is that I'm still faster than RSAref when using standard C, -without using the 'long long' data type :-), %35 faster for 512bit and we -scale up to 3.2 times faster for the 'default linux' build. I should mention -that people should 'try' to use either x86-lnx.s (elf), x86-lnxa.s or -x86-sol.s for any x86 based unix they are building on. The only problems -with be with syntax but the performance gain is quite large, especially for -servers. The code is very simple, you just need to modify the 'header'. - -The message is, if you are stuck using RSAref, the RSA performance will be -bad. Considering the code was compiled for a pentium, the 486DX66 number -would indicate 'Use RSAref and turn you Pentium 100 into a 486DX66' :-). -[ As of verson 0.6.1, it would be correct to say 'turn you pentium 100 - into a 486DX33' :-) ] - -I won't tell people if the DLL's are using RSAref or my stuff if no-one -asks :-). - -eric - -PS while I know I could speed things up further, I will probably not do - so due to the effort involved. I did do some timings on the - SSLeay bignum format -> RSAref number format conversion that occurs - each time RSAref is used by SSLeay, and the numbers are trivial. - 0.00012s a call for 512bit vs 0.149s for the time spent in the function. - 0.00018s for 1024bit vs 0.938s. Insignificant. - So the 'way to go', to support faster RSA libraries, if people are keen, - is to write 'glue' code in a similar way that I do for RSAref and send it - to me :-). - My base library still has the advantage of being able to operate on - any size numbers, and is not that far from the performance from the - leaders in the field. (-%30?) - [ Well as of 0.6.1 I am now the leader in the filed on x86 (we at - least very close :-) ] - - I suppose I should also mention some other numbers RSAref numbers, again - on my Pentium. - DES CBC EDE-DES MD5 - RSAref linux 830k/s 302k/s 4390k/s - SSLeay linux 855k/s 319k/s 10025k/s - SSLeay NT 1158k/s 410k/s 10470k/s - SSLeay w31 378k/s 143k/s 2383k/s (fully 16bit) - - Got to admit that Visual C++ 4.[01] is a damn fine compiler :-) --- -Eric Young | BOOL is tri-state according to Bill Gates. -AARNet: eay@cryptsoft.com | RTFM Win32 GetMessage(). - - - - -==== ssl-ciph.doc ======================================================== - -This is a quick high level summery of how things work now. - -Each SSLv2 and SSLv3 cipher is composed of 4 major attributes plus a few extra -minor ones. - -They are 'The key exchange algorithm', which is RSA for SSLv2 but can also -be Diffle-Hellman for SSLv3. - -An 'Authenticion algorithm', which can be RSA, Diffle-Helman, DSS or -none. - -The cipher - -The MAC digest. - -A cipher can also be an export cipher and is either an SSLv2 or a -SSLv3 ciphers. - -To specify which ciphers to use, one can either specify all the ciphers, -one at a time, or use 'aliases' to specify the preference and order for -the ciphers. - -There are a large number of aliases, but the most importaint are -kRSA, kDHr, kDHd and kDHE for key exchange types. - -aRSA, aDSS, aNULL and aDH for authentication -DES, 3DES, RC4, RC2, IDEA and eNULL for ciphers -MD5, SHA0 and SHA1 digests - -Now where this becomes interesting is that these can be put together to -specify the order and ciphers you wish to use. - -To speed this up there are also aliases for certian groups of ciphers. -The main ones are -SSLv2 - all SSLv2 ciphers -SSLv3 - all SSLv3 ciphers -EXP - all export ciphers -LOW - all low strngth ciphers (no export ciphers, normally single DES) -MEDIUM - 128 bit encryption -HIGH - Triple DES - -These aliases can be joined in a : separated list which specifies to -add ciphers, move them to the current location and delete them. - -A simpler way to look at all of this is to use the 'ssleay ciphers -v' command. -The default library cipher spec is -!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP -which means, first, remove from consideration any ciphers that do not -authenticate. Next up, use ciphers using RC4 and RSA. Next include the HIGH, -MEDIUM and the LOW security ciphers. Finish up by adding all the export -ciphers on the end, then 'pull' all the SSLv2 and export ciphers to -the end of the list. - -The results are -$ ssleay ciphers -v '!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP' - -RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1 -RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 -EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 -EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 -DES-CBC3-SHA SSLv3 Kx=RSA Au=RSA Enc=3DES(168) Mac=SHA1 -IDEA-CBC-MD5 SSLv3 Kx=RSA Au=RSA Enc=IDEA(128) Mac=SHA1 -EDH-RSA-DES-CBC-SHA SSLv3 Kx=DH Au=RSA Enc=DES(56) Mac=SHA1 -EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH Au=DSS Enc=DES(56) Mac=SHA1 -DES-CBC-SHA SSLv3 Kx=RSA Au=RSA Enc=DES(56) Mac=SHA1 -DES-CBC3-MD5 SSLv2 Kx=RSA Au=RSA Enc=3DES(168) Mac=MD5 -DES-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=DES(56) Mac=MD5 -IDEA-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=IDEA(128) Mac=MD5 -RC2-CBC-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC2(128) Mac=MD5 -RC4-MD5 SSLv2 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 -EXP-EDH-RSA-DES-CBC SSLv3 Kx=DH(512) Au=RSA Enc=DES(40) Mac=SHA1 export -EXP-EDH-DSS-DES-CBC-SHA SSLv3 Kx=DH(512) Au=DSS Enc=DES(40) Mac=SHA1 export -EXP-DES-CBC-SHA SSLv3 Kx=RSA(512) Au=RSA Enc=DES(40) Mac=SHA1 export -EXP-RC2-CBC-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export -EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export -EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export -EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export - -I would recoment people use the 'ssleay ciphers -v "text"' -command to check what they are going to use. - -Anyway, I'm falling asleep here so I'll do some more tomorrow. - -eric - -==== ssl.doc ======================================================== - -SSL_CTX_sessions(SSL_CTX *ctx) - the session-id hash table. - -/* Session-id cache stats */ -SSL_CTX_sess_number -SSL_CTX_sess_connect -SSL_CTX_sess_connect_good -SSL_CTX_sess_accept -SSL_CTX_sess_accept_good -SSL_CTX_sess_hits -SSL_CTX_sess_cb_hits -SSL_CTX_sess_misses -SSL_CTX_sess_timeouts - -/* Session-id application notification callbacks */ -SSL_CTX_sess_set_new_cb -SSL_CTX_sess_get_new_cb -SSL_CTX_sess_set_get_cb -SSL_CTX_sess_get_get_cb - -/* Session-id cache operation mode */ -SSL_CTX_set_session_cache_mode -SSL_CTX_get_session_cache_mode - -/* Set default timeout values to use. */ -SSL_CTX_set_timeout -SSL_CTX_get_timeout - -/* Global SSL initalisation informational callback */ -SSL_CTX_set_info_callback -SSL_CTX_get_info_callback -SSL_set_info_callback -SSL_get_info_callback - -/* If the SSL_accept/SSL_connect returned with -1, these indicate when - * we should re-call *. -SSL_want -SSL_want_nothing -SSL_want_read -SSL_want_write -SSL_want_x509_lookup - -/* Where we are in SSL initalisation, used in non-blocking, perhaps - * have a look at ssl/bio_ssl.c */ -SSL_state -SSL_is_init_finished -SSL_in_init -SSL_in_connect_init -SSL_in_accept_init - -/* Used to set the 'inital' state so SSL_in_connect_init and SSL_in_accept_init - * can be used to work out which function to call. */ -SSL_set_connect_state -SSL_set_accept_state - -/* Where to look for certificates for authentication */ -SSL_set_default_verify_paths /* calles SSL_load_verify_locations */ -SSL_load_verify_locations - -/* get info from an established connection */ -SSL_get_session -SSL_get_certificate -SSL_get_SSL_CTX - -SSL_CTX_new -SSL_CTX_free -SSL_new -SSL_clear -SSL_free - -SSL_CTX_set_cipher_list -SSL_get_cipher -SSL_set_cipher_list -SSL_get_cipher_list -SSL_get_shared_ciphers - -SSL_accept -SSL_connect -SSL_read -SSL_write - -SSL_debug - -SSL_get_read_ahead -SSL_set_read_ahead -SSL_set_verify - -SSL_pending - -SSL_set_fd -SSL_set_rfd -SSL_set_wfd -SSL_set_bio -SSL_get_fd -SSL_get_rbio -SSL_get_wbio - -SSL_use_RSAPrivateKey -SSL_use_RSAPrivateKey_ASN1 -SSL_use_RSAPrivateKey_file -SSL_use_PrivateKey -SSL_use_PrivateKey_ASN1 -SSL_use_PrivateKey_file -SSL_use_certificate -SSL_use_certificate_ASN1 -SSL_use_certificate_file - -ERR_load_SSL_strings -SSL_load_error_strings - -/* human readable version of the 'state' of the SSL connection. */ -SSL_state_string -SSL_state_string_long -/* These 2 report what kind of IO operation the library was trying to - * perform last. Probably not very usefull. */ -SSL_rstate_string -SSL_rstate_string_long - -SSL_get_peer_certificate - -SSL_SESSION_new -SSL_SESSION_print_fp -SSL_SESSION_print -SSL_SESSION_free -i2d_SSL_SESSION -d2i_SSL_SESSION - -SSL_get_time -SSL_set_time -SSL_get_timeout -SSL_set_timeout -SSL_copy_session_id -SSL_set_session -SSL_CTX_add_session -SSL_CTX_remove_session -SSL_CTX_flush_sessions - -BIO_f_ssl - -/* used to hold information as to why a certificate verification failed */ -SSL_set_verify_result -SSL_get_verify_result - -/* can be used by the application to associate data with an SSL structure. - * It needs to be 'free()ed' by the application */ -SSL_set_app_data -SSL_get_app_data - -/* The following all set values that are kept in the SSL_CTX but - * are used as the default values when an SSL session is created. - * They are over writen by the relevent SSL_xxxx functions */ - -/* SSL_set_verify */ -void SSL_CTX_set_default_verify - -/* This callback, if set, totaly overrides the normal SSLeay verification - * functions and should return 1 on success and 0 on failure */ -void SSL_CTX_set_cert_verify_callback - -/* The following are the same as the equivilent SSL_xxx functions. - * Only one copy of this information is kept and if a particular - * SSL structure has a local override, it is totally separate structure. - */ -int SSL_CTX_use_RSAPrivateKey -int SSL_CTX_use_RSAPrivateKey_ASN1 -int SSL_CTX_use_RSAPrivateKey_file -int SSL_CTX_use_PrivateKey -int SSL_CTX_use_PrivateKey_ASN1 -int SSL_CTX_use_PrivateKey_file -int SSL_CTX_use_certificate -int SSL_CTX_use_certificate_ASN1 -int SSL_CTX_use_certificate_file - - -==== ssl_ctx.doc ======================================================== - -This is now a bit dated, quite a few of the SSL_ functions could be -SSL_CTX_ functions. I will update this in the future. 30 Aug 1996 - -From eay@orb.mincom.oz.au Mon Dec 11 21:37:08 1995 -Received: by orb.mincom.oz.au id AA00696 - (5.65c/IDA-1.4.4 for eay); Mon, 11 Dec 1995 11:37:08 +1000 -Date: Mon, 11 Dec 1995 11:37:08 +1000 (EST) -From: Eric Young <eay@mincom.oz.au> -X-Sender: eay@orb -To: sameer <sameer@c2.org> -Cc: Eric Young <eay@mincom.oz.au> -Subject: Re: PEM_readX509 oesn't seem to be working -In-Reply-To: <199512110102.RAA12521@infinity.c2.org> -Message-Id: <Pine.SOL.3.91.951211112115.28608D-100000@orb> -Mime-Version: 1.0 -Content-Type: TEXT/PLAIN; charset=US-ASCII -Status: RO -X-Status: - -On Sun, 10 Dec 1995, sameer wrote: -> OK, that's solved. I've found out that it is saying "no -> certificate set" in SSL_accept because s->conn == NULL -> so there is some place I need to initialize s->conn that I am -> not initializing it. - -The full order of things for a server should be. - -ctx=SSL_CTX_new(); - -/* The next line should not really be using ctx->cert but I'll leave it - * this way right now... I don't want a X509_ routine to know about an SSL - * structure, there should be an SSL_load_verify_locations... hmm, I may - * add it tonight. - */ -X509_load_verify_locations(ctx->cert,CAfile,CApath); - -/* Ok now for each new connection we do the following */ -con=SSL_new(ctx); -SSL_set_fd(con,s); -SSL_set_verify(con,verify,verify_callback); - -/* set the certificate and private key to use. */ -SSL_use_certificate_ASN1(con,X509_certificate); -SSL_use_RSAPrivateKey_ASN1(con,RSA_private_key); - -SSL_accept(con); - -SSL_read(con)/SSL_write(con); - -There is a bit more than that but that is basically the structure. - -Create a context and specify where to lookup certificates. - -foreach connection - { - create a SSL structure - set the certificate and private key - do a SSL_accept - - we should now be ok - } - -eric --- -Eric Young | Signature removed since it was generating -AARNet: eay@mincom.oz.au | more followups than the message contents :-) - - - -==== ssleay.doc ======================================================== - -SSLeay: a cryptographic kitchen sink. - -1st December 1995 -Way back at the start of April 1995, I was looking for a mindless -programming project. A friend of mine (Tim Hudson) said "why don't you do SSL, -it has DES encryption in it and I would not mind using it in a SSL telnet". -While it was true I had written a DES library in previous years, litle -did I know what an expansive task SSL would turn into. - -First of all, the SSL protocol contains DES encryption. Well and good. My -DES library was fast and portable. It also contained the RSA's RC4 stream -cipher. Again, not a problem, some-one had just posted to sci.crypt -something that was claimed to be RC4. It also contained IDEA, I had the -specifications, not a problem to implement. MD5, an RFC, trivial, at most -I could spend a week or so trying to see if I could speed up the -implementation. All in all a nice set of ciphers. -Then the first 'expantion of the scope', RSA public key -encryption. Since I did not knowing a thing about public key encryption -or number theory, this appeared quite a daunting task. Just writing a -big number library would be problomatic in itself, let alone making it fast. -At this point the scope of 'implementing SSL' expands eponentialy. -First of all, the RSA private keys were being kept in ASN.1 format. -Thankfully the RSA PKCS series of documents explains this format. So I now -needed to be able to encode and decode arbitary ASN.1 objects. The Public -keys were embeded in X509 certificates. Hmm... these are not only -ASN.1 objects but they make up a heirachy of authentication. To -authenticate a X509 certificate one needs to retrieve it's issuers -certificate etc etc. Hmm..., so I also need to implement some kind -of certificate management software. I would also have to implement -software to authenticate certificates. At this point the support code made -the SSL part of my library look quite small. -Around this time, the first version of SSLeay was released. - -Ah, but here was the problem, I was not happy with the code so far. As may -have become obvious, I had been treating all of this as a learning -exersize, so I have completely written the library myself. As such, due -to the way it had grown like a fungus, much of the library was not -'elagent' or neat. There were global and static variables all over the -place, the SSL part did not even handle non-blocking IO. -The Great rewrite began. - -As of this point in time, the 'Great rewrite' has almost finished. So what -follows is an approximate list of what is actually SSLeay 0.5.0 - -/********* This needs to be updated for 0.6.0+ *************/ - ---- -The library contains the following routines. Please note that most of these -functions are not specfic for SSL or any other particular cipher -implementation. I have tried to make all the routines as general purpose -as possible. So you should not think of this library as an SSL -implemtation, but rather as a library of cryptographic functions -that also contains SSL. I refer to each of these function groupings as -libraries since they are often capable of functioning as independant -libraries - -First up, the general ciphers and message digests supported by the library. - -MD2 rfc???, a standard 'by parts' interface to this algorithm. -MD5 rfc???, the same type of interface as for the MD2 library except a - different algorithm. -SHA THe Secure Hash Algorithm. Again the same type of interface as - MD2/MD5 except the digest is 20 bytes. -SHA1 The 'revised' version of SHA. Just about identical to SHA except - for one tweak of an inner loop. -DES This is my libdes library that has been floating around for the last - few years. It has been enhanced for no other reason than completeness. - It now supports ecb, cbc, cfb, ofb, cfb64, ofb64 in normal mode and - triple DES modes of ecb, cbc, cfb64 and ofb64. cfb64 and ofb64 are - functional interfaces to the 64 bit modes of cfb and ofb used in - such a way thay they function as single character interfaces. -RC4 The RSA Inc. stream cipher. -RC2 The RSA Inc. block cipher. -IDEA An implmentation of the IDEA cipher, the library supports ecb, cbc, - cfb64 and ofb64 modes of operation. - -Now all the above mentioned ciphers and digests libraries support high -speed, minimal 'crap in the way' type interfaces. For fastest and -lowest level access, these routines should be used directly. - -Now there was also the matter of public key crypto systems. These are -based on large integer arithmatic. - -BN This is my large integer library. It supports all the normal - arithmentic operations. It uses malloc extensivly and as such has - no limits of the size of the numbers being manipulated. If you - wish to use 4000 bit RSA moduli, these routines will handle it. - This library also contains routines to 'generate' prime numbers and - to test for primality. The RSA and DH libraries sit on top of this - library. As of this point in time, I don't support SHA, but - when I do add it, it will just sit on top of the routines contained - in this library. -RSA This implements the RSA public key algorithm. It also contains - routines that will generate a new private/public key pair. - All the RSA functions conform to the PKCS#1 standard. -DH This is an implementation of the - Diffie-Hellman protocol. There are all the require routines for - the protocol, plus extra routines that can be used to generate a - strong prime for use with a specified generator. While this last - routine is not generally required by applications implementing DH, - It is present for completeness and because I thing it is much - better to be able to 'generate' your own 'magic' numbers as oposed - to using numbers suplied by others. I conform to the PKCS#3 - standard where required. - -You may have noticed the preceeding section mentions the 'generation' of -prime numbers. Now this requries the use of 'random numbers'. - -RAND This psuedo-random number library is based on MD5 at it's core - and a large internal state (2k bytes). Once you have entered enough - seed data into this random number algorithm I don't feel - you will ever need to worry about it generating predictable output. - Due to the way I am writing a portable library, I have left the - issue of how to get good initial random seed data upto the - application but I do have support routines for saving and loading a - persistant random number state for use between program runs. - -Now to make all these ciphers easier to use, a higher level -interface was required. In this form, the same function would be used to -encrypt 'by parts', via any one of the above mentioned ciphers. - -EVP The Digital EnVeloPe library is quite large. At it's core are - function to perform encryption and decryption by parts while using - an initial parameter to specify which of the 17 different ciphers - or 4 different message digests to use. On top of these are implmented - the digital signature functions, sign, verify, seal and open. - Base64 encoding of binary data is also done in this library. - -PEM rfc???? describe the format for Privacy Enhanced eMail. - As part of this standard, methods of encoding digital enveloped - data is an ascii format are defined. As such, I use a form of these - to encode enveloped data. While at this point in time full support - for PEM has not been built into the library, a minimal subset of - the secret key and Base64 encoding is present. These reoutines are - mostly used to Ascii encode binary data with a 'type' associated - with it and perhaps details of private key encryption used to - encrypt the data. - -PKCS7 This is another Digital Envelope encoding standard which uses ASN.1 - to encode the data. At this point in time, while there are some - routines to encode and decode this binary format, full support is - not present. - -As Mentioned, above, there are several different ways to encode -data structures. - -ASN1 This library is more a set of primatives used to encode the packing - and unpacking of data structures. It is used by the X509 - certificate standard and by the PKCS standards which are used by - this library. It also contains routines for duplicating and signing - the structures asocisated with X509. - -X509 The X509 library contains routines for packing and unpacking, - verifying and just about every thing else you would want to do with - X509 certificates. - -PKCS7 PKCS-7 is a standard for encoding digital envelope data - structures. At this point in time the routines will load and save - DER forms of these structees. They need to be re-worked to support - the BER form which is the normal way PKCS-7 is encoded. If the - previous 2 sentances don't make much sense, don't worry, this - library is not used by this version of SSLeay anyway. - -OBJ ASN.1 uses 'object identifiers' to identify objects. A set of - functions were requred to translate from ASN.1 to an intenger, to a - character string. This library provieds these translations - -Now I mentioned an X509 library. X509 specified a hieachy of certificates -which needs to be traversed to authenticate particular certificates. - -METH This library is used to push 'methods' of retrieving certificates - into the library. There are some supplied 'methods' with SSLeay - but applications can add new methods if they so desire. - This library has not been finished and is not being used in this - version. - -Now all the above are required for use in the initial point of this project. - -SSL The SSL protocol. This is a full implmentation of SSL v 2. It - support both server and client authentication. SSL v 3 support - will be added when the SSL v 3 specification is released in it's - final form. - -Now quite a few of the above mentioned libraries rely on a few 'complex' -data structures. For each of these I have a library. - -Lhash This is a hash table library which is used extensivly. - -STACK An implemetation of a Stack data structure. - -BUF A simple character array structure that also support a function to - check that the array is greater that a certain size, if it is not, - it is realloced so that is it. - -TXT_DB A simple memory based text file data base. The application can specify - unique indexes that will be enforced at update time. - -CONF Most of the programs written for this library require a configuration - file. Instead of letting programs constantly re-implment this - subsystem, the CONF library provides a consistant and flexable - interface to not only configuration files but also environment - variables. - -But what about when something goes wrong? -The one advantage (and perhaps disadvantage) of all of these -functions being in one library was the ability to implement a -single error reporting system. - -ERR This library is used to report errors. The error system records - library number, function number (in the library) and reason - number. Multiple errors can be reported so that an 'error' trace - is created. The errors can be printed in numeric or textual form. - - -==== ssluse.doc ======================================================== - -We have an SSL_CTX which contains global information for lots of -SSL connections. The session-id cache and the certificate verificate cache. -It also contains default values for use when certificates are used. - -SSL_CTX - default cipher list - session-id cache - certificate cache - default session-id timeout period - New session-id callback - Required session-id callback - session-id stats - Informational callback - Callback that is set, overrides the SSLeay X509 certificate - verification - The default Certificate/Private Key pair - Default read ahead mode. - Default verify mode and verify callback. These are not used - if the over ride callback mentioned above is used. - -Each SSL can have the following defined for it before a connection is made. - -Certificate -Private key -Ciphers to use -Certificate verify mode and callback -IO object to use in the comunication. -Some 'read-ahead' mode information. -A previous session-id to re-use. - -A connection is made by using SSL_connect or SSL_accept. -When non-blocking IO is being used, there are functions that can be used -to determin where and why the SSL_connect or SSL_accept did not complete. -This information can be used to recall the functions when the 'error' -condition has dissapeared. - -After the connection has been made, information can be retrived about the -SSL session and the session-id values that have been decided upon. -The 'peer' certificate can be retrieved. - -The session-id values include -'start time' -'timeout length' - - - -==== stack.doc ======================================================== - -The stack data structure is used to store an ordered list of objects. -It is basically misnamed to call it a stack but it can function that way -and that is what I originally used it for. Due to the way element -pointers are kept in a malloc()ed array, the most efficient way to use this -structure is to add and delete elements from the end via sk_pop() and -sk_push(). If you wish to do 'lookups' sk_find() is quite efficient since -it will sort the stack (if required) and then do a binary search to lookup -the requested item. This sorting occurs automatically so just sk_push() -elements on the stack and don't worry about the order. Do remember that if -you do a sk_find(), the order of the elements will change. - -You should never need to 'touch' this structure directly. -typedef struct stack_st - { - unsigned int num; - char **data; - int sorted; - - unsigned int num_alloc; - int (*comp)(); - } STACK; - -'num' holds the number of elements in the stack, 'data' is the array of -elements. 'sorted' is 1 is the list has been sorted, 0 if not. - -num_alloc is the number of 'nodes' allocated in 'data'. When num becomes -larger than num_alloc, data is realloced to a larger size. -If 'comp' is set, it is a function that is used to compare 2 of the items -in the stack. The function should return -1, 0 or 1, depending on the -ordering. - -#define sk_num(sk) ((sk)->num) -#define sk_value(sk,n) ((sk)->data[n]) - -These 2 macros should be used to access the number of elements in the -'stack' and to access a pointer to one of the values. - -STACK *sk_new(int (*c)()); - This creates a new stack. If 'c', the comparison function, is not -specified, the various functions that operate on a sorted 'stack' will not -work (sk_find()). NULL is returned on failure. - -void sk_free(STACK *); - This function free()'s a stack structure. The elements in the -stack will not be freed so one should 'pop' and free all elements from the -stack before calling this function or call sk_pop_free() instead. - -void sk_pop_free(STACK *st; void (*func)()); - This function calls 'func' for each element on the stack, passing -the element as the argument. sk_free() is then called to free the 'stack' -structure. - -int sk_insert(STACK *sk,char *data,int where); - This function inserts 'data' into stack 'sk' at location 'where'. -If 'where' is larger that the number of elements in the stack, the element -is put at the end. This function tends to be used by other 'stack' -functions. Returns 0 on failure, otherwise the number of elements in the -new stack. - -char *sk_delete(STACK *st,int loc); - Remove the item a location 'loc' from the stack and returns it. -Returns NULL if the 'loc' is out of range. - -char *sk_delete_ptr(STACK *st, char *p); - If the data item pointed to by 'p' is in the stack, it is deleted -from the stack and returned. NULL is returned if the element is not in the -stack. - -int sk_find(STACK *st,char *data); - Returns the location that contains a value that is equal to -the 'data' item. If the comparison function was not set, this function -does a linear search. This function actually qsort()s the stack if it is not -in order and then uses bsearch() to do the initial search. If the -search fails,, -1 is returned. For mutliple items with the same -value, the index of the first in the array is returned. - -int sk_push(STACK *st,char *data); - Append 'data' to the stack. 0 is returned if there is a failure -(due to a malloc failure), else 1. This is -sk_insert(st,data,sk_num(st)); - -int sk_unshift(STACK *st,char *data); - Prepend 'data' to the front (location 0) of the stack. This is -sk_insert(st,data,0); - -char *sk_shift(STACK *st); - Return and delete from the stack the first element in the stack. -This is sk_delete(st,0); - -char *sk_pop(STACK *st); - Return and delete the last element on the stack. This is -sk_delete(st,sk_num(sk)-1); - -void sk_zero(STACK *st); - Removes all items from the stack. It does not 'free' -pointers but is a quick way to clear a 'stack of references'. - -==== threads.doc ======================================================== - -How to compile SSLeay for multi-threading. - -Well basically it is quite simple, set the compiler flags and build. -I have only really done much testing under Solaris and Windows NT. -If you library supports localtime_r() and gmtime_r() add, --DTHREADS to the makefile parameters. You can probably survive with out -this define unless you are going to have multiple threads generating -certificates at once. It will not affect the SSL side of things. - -The approach I have taken to doing locking is to make the application provide -callbacks to perform locking and so that the SSLeay library can distinguish -between threads (for the error state). - -To have a look at an example program, 'cd mt; vi mttest.c'. -To build under solaris, sh solaris.sh, for Windows NT or Windows 95, -win32.bat - -This will build mttest which will fire up 10 threads that talk SSL -to each other 10 times. -To enable everything to work, the application needs to call - -CRYPTO_set_id_callback(id_function); -CRYPTO_set_locking_callback(locking_function); - -before any multithreading is started. -id_function does not need to be defined under Windows NT or 95, the -correct function will be called if it is not. Under unix, getpid() -is call if the id_callback is not defined, for Solaris this is wrong -(since threads id's are not pid's) but under Linux it is correct -(threads are just processes sharing the data segement). - -The locking_callback is used to perform locking by the SSLeay library. -eg. - -void solaris_locking_callback(mode,type,file,line) -int mode; -int type; -char *file; -int line; - { - if (mode & CRYPTO_LOCK) - mutex_lock(&(lock_cs[type])); - else - mutex_unlock(&(lock_cs[type])); - } - -Now in this case I have used mutexes instead of read/write locks, since they -are faster and there are not many read locks in SSLeay, you may as well -always use write locks. file and line are __FILE__ and __LINE__ from -the compile and can be usefull when debugging. - -Now as you can see, 'type' can be one of a range of values, these values are -defined in crypto/crypto.h -CRYPTO_get_lock_name(type) will return a text version of what the lock is. -There are CRYPTO_NUM_LOCKS locks required, so under solaris, the setup -for multi-threading can be - -static mutex_t lock_cs[CRYPTO_NUM_LOCKS]; - -void thread_setup() - { - int i; - - for (i=0; i<CRYPTO_NUM_LOCKS; i++) - mutex_init(&(lock_cs[i]),USYNC_THREAD,NULL); - CRYPTO_set_id_callback((unsigned long (*)())solaris_thread_id); - CRYPTO_set_locking_callback((void (*)())solaris_locking_callback); - } - -As a final note, under Windows NT or Windows 95, you have to be careful -not to mix the various threaded, unthreaded and debug libraries. -Normally if they are mixed incorrectly, mttest will crash just after printing -out some usage statistics at the end. This is because the -different system libraries use different malloc routines and if -data is malloc()ed inside crypt32.dll or ssl32.dll and then free()ed by a -different library malloc, things get very confused. - -The default SSLeay DLL builds use /MD, so if you use this on your -application, things will work as expected. If you use /MDd, -you will probably have to rebuild SSLeay using this flag. -I should modify util/mk1mf.pl so it does all this correctly, but -this has not been done yet. - -One last warning. Because locking overheads are actually quite large, the -statistics collected against the SSL_CTX for successfull connections etc -are not locked when updated. This does make it possible for these -values to be slightly lower than they should be, if you are -running multithreaded on a multi-processor box, but this does not really -matter much. - - -==== txt_db.doc ======================================================== - -TXT_DB, a simple text based in memory database. - -It holds rows of ascii data, for which the only special character is '\0'. -The rows can be of an unlimited length. - -==== why.doc ======================================================== - -This file is more of a note for other people who wish to understand why -the build environment is the way it is :-). - -The include files 'depend' as follows. -Each of -crypto/*/*.c includes crypto/cryptlib.h -ssl/*.c include ssl/ssl_locl.h -apps/*.c include apps/apps.h -crypto/cryptlib.h, ssl/ssl_locl.h and apps/apps.h -all include e_os.h which contains OS/environment specific information. -If you need to add something todo with a particular environment, -add it to this file. It is worth remembering that quite a few libraries, -like lhash, des, md, sha etc etc do not include crypto/cryptlib.h. This -is because these libraries should be 'independantly compilable' and so I -try to keep them this way. -e_os.h is not so much a part of SSLeay, as the placing in one spot all the -evil OS dependant muck. - -I wanted to automate as many things as possible. This includes -error number generation. A -make errors -will scan the source files for error codes, append them to the correct -header files, and generate the functions to print the text version -of the error numbers. So don't even think about adding error numbers by -hand, put them in the form -XXXerr(XXXX_F_XXXX,YYYY_R_YYYY); -on line and it will be automatically picked up my a make errors. - -In a similar vein, programs to be added into ssleay in the apps directory -just need to have an entry added to E_EXE in makefile.ssl and -everthing will work as expected. Don't edit progs.h by hand. - -make links re-generates the symbolic links that are used. The reason why -I keep everything in its own directory, and don't put all the -test programs and header files in 'test' and 'include' is because I want -to keep the 'sub-libraries' independant. I still 'pull' out -indervidual libraries for use in specific projects where the code is -required. I have used the 'lhash' library in just about every software -project I have worked on :-). - -make depend generates dependancies and -make dclean removes them. - -You will notice that I use perl quite a bit when I could be using 'sed'. -The reason I decided to do this was to just stick to one 'extra' program. -For Windows NT, I have perl and no sed. - -The util/mk1mf.pl program can be used to generate a single makefile. -I use this because makefiles under Microsoft are horrific. -Each C compiler seems to have different linker formats, which have -to be used because the retarted C compilers explode when you do -cl -o file *.o. - -Now some would argue that I should just use the single makefile. I don't -like it during develoment for 2 reasons. First, the actuall make -command takes a long time. For my current setup, if I'm in -crypto/bn and I type make, only the crypto/bn directory gets rebuilt, -which is nice when you are modifying prototypes in bn.h which -half the SSLeay depends on. The second is that to add a new souce file -I just plonk it in at the required spot in the local makefile. This -then alows me to keep things local, I don't need to modify a 'global' -tables (the make for unix, the make for NT, the make for w31...). -When I am ripping apart a library structure, it is nice to only -have to worry about one directory :-). - -Having said all this, for the hell of it I put together 2 files that -#include all the souce code (generated by doing a ls */*.o after a build). -crypto.c takes only 30 seconds to build under NT and 2 minutes under linux -for my pentium100. Much faster that the normal build :-). -Again, the problem is that when using libraries, every program linked -to libcrypto.a would suddenly get 330k of library when it may only need -1k. This technique does look like a nice way to do shared libraries though. - -Oh yes, as a final note, to 'build' a distribution, I just type -make dist. -This cleans and packages everything. The directory needs to be called -SSLeay since the make does a 'cd ..' and renames and tars things up. - -==== req.1 ======================================================== - -The 'req' command is used to manipulate and deal with pkcs#10 -certificate requests. - -It's default mode of operation is to load a certificate and then -write it out again. - -By default the 'req' is read from stdin in 'PEM' format. -The -inform option can be used to specify 'pem' format or 'der' -format. PEM format is the base64 encoding of the DER format. - -By default 'req' then writes the request back out. -outform can be used -to indicate the desired output format, be it 'pem' or 'der'. - -To specify an input file, use the '-in' option and the '-out' option -can be used to specify the output file. - -If you wish to perform a command and not output the certificate -request afterwards, use the '-noout' option. - -When a certificate is loaded, it can be printed in a human readable -ascii format via the '-text' option. - -To check that the signature on a certificate request is correct, use -the '-verify' option to make sure that the private key contained in the -certificate request corresponds to the signature. - -Besides the default mode, there is also the 'generate a certificate -request' mode. There are several flags that trigger this mode. - --new will generate a new RSA key (if required) and then prompts -the user for details for the certificate request. --newkey has an argument that is the number of bits to make the new -key. This function also triggers '-new'. - -The '-new' option can have a key to use specified instead of having to -load one, '-key' is used to specify the file containg the key. --keyform can be used to specify the format of the key. Only -'pem' and 'der' formats are supported, later, 'netscape' format may be added. - -Finally there is the '-x509' options which makes req output a self -signed x509 certificate instead of a certificate request. - -Now as you may have noticed, there are lots of default options that -cannot be specified via the command line. They are held in a 'template' -or 'configuration file'. The -config option specifies which configuration -file to use. See conf.doc for details on the syntax of this file. - -The req command uses the 'req' section of the config file. - ---- -# The following variables are defined. For this example I will populate -# the various values -[ req ] -default_bits = 512 # default number of bits to use. -default_keyfile = testkey.pem # Where to write the generated keyfile - # if not specified. -distinguished_name= req_dn # The section that contains the - # information about which 'object' we - # want to put in the DN. -attributes = req_attr # The objects we want for the - # attributes field. -encrypt_rsa_key = no # Should we encrypt newly generated - # keys. I strongly recommend 'yes'. - -# The distinguished name section. For the following entries, the -# object names must exist in the SSLeay header file objects.h. If they -# do not, they will be silently ignored. The entries have the following -# format. -# <object_name> => string to prompt with -# <object_name>_default => default value for people -# <object_name>_value => Automatically use this value for this field. -# <object_name>_min => minimum number of characters for data (def. 0) -# <object_name>_max => maximum number of characters for data (def. inf.) -# All of these entries are optional except for the first one. -[ req_dn ] -countryName = Country Name (2 letter code) -countryName_default = AU - -stateOrProvinceName = State or Province Name (full name) -stateOrProvinceName_default = Queensland - -localityName = Locality Name (eg, city) - -organizationName = Organization Name (eg, company) -organizationName_default = Mincom Pty Ltd - -organizationalUnitName = Organizational Unit Name (eg, section) -organizationalUnitName_default = MTR - -commonName = Common Name (eg, YOUR name) -commonName_max = 64 - -emailAddress = Email Address -emailAddress_max = 40 - -# The next section is the attributes section. This is exactly the -# same as for the previous section except that the resulting objects are -# put in the attributes field. -[ req_attr ] -challengePassword = A challenge password -challengePassword_min = 4 -challengePassword_max = 20 - -unstructuredName = An optional company name - ----- -Also note that the order that attributes appear in this file is the -order they will be put into the distinguished name. - -Once this request has been generated, it can be sent to a CA for -certifying. - ----- -A few quick examples.... - -To generate a new request and a new key -req -new - -To generate a new request and a 1058 bit key -req -newkey 1058 - -To generate a new request using a pre-existing key -req -new -key key.pem - -To generate a self signed x509 certificate from a certificate -request using a supplied key, and we want to see the text form of the -output certificate (which we will put in the file selfSign.pem -req -x509 -in req.pem -key key.pem -text -out selfSign.pem - -Verify that the signature is correct on a certificate request. -req -verify -in req.pem - -Verify that the signature was made using a specified public key. -req -verify -in req.pem -key key.pem - -Print the contents of a certificate request -req -text -in req.pem - -==== danger ======================================================== - -If you specify a SSLv2 cipher, and the mode is SSLv23 and the server -can talk SSLv3, it will claim there is no cipher since you should be -using SSLv3. - -When tracing debug stuff, remember BIO_s_socket() is different to -BIO_s_connect(). - -BSD/OS assember is not working - diff --git a/openssl/doc/standards.txt b/openssl/doc/standards.txt deleted file mode 100644 index 7bada8d..0000000 --- a/openssl/doc/standards.txt +++ /dev/null @@ -1,285 +0,0 @@ -Standards related to OpenSSL -============================ - -[Please, this is currently a draft. I made a first try at finding - documents that describe parts of what OpenSSL implements. There are - big gaps, and I've most certainly done something wrong. Please - correct whatever is... Also, this note should be removed when this - file is reaching a somewhat correct state. -- Richard Levitte] - - -All pointers in here will be either URL's or blobs of text borrowed -from miscellaneous indexes, like rfc-index.txt (index of RFCs), -1id-index.txt (index of Internet drafts) and the like. - -To find the latest possible RFCs, it's recommended to either browse -ftp://ftp.isi.edu/in-notes/ or go to http://www.rfc-editor.org/ and -use the search mechanism found there. -To find the latest possible Internet drafts, it's recommended to -browse ftp://ftp.isi.edu/internet-drafts/. -To find the latest possible PKCS, it's recommended to browse -http://www.rsasecurity.com/rsalabs/pkcs/. - - -Implemented: ------------- - -These are documents that describe things that are implemented (in -whole or at least great parts) in OpenSSL. - -1319 The MD2 Message-Digest Algorithm. B. Kaliski. April 1992. - (Format: TXT=25661 bytes) (Status: INFORMATIONAL) - -1320 The MD4 Message-Digest Algorithm. R. Rivest. April 1992. (Format: - TXT=32407 bytes) (Status: INFORMATIONAL) - -1321 The MD5 Message-Digest Algorithm. R. Rivest. April 1992. (Format: - TXT=35222 bytes) (Status: INFORMATIONAL) - -2246 The TLS Protocol Version 1.0. T. Dierks, C. Allen. January 1999. - (Format: TXT=170401 bytes) (Status: PROPOSED STANDARD) - -2268 A Description of the RC2(r) Encryption Algorithm. R. Rivest. - January 1998. (Format: TXT=19048 bytes) (Status: INFORMATIONAL) - -2315 PKCS 7: Cryptographic Message Syntax Version 1.5. B. Kaliski. - March 1998. (Format: TXT=69679 bytes) (Status: INFORMATIONAL) - -PKCS#8: Private-Key Information Syntax Standard - -PKCS#12: Personal Information Exchange Syntax Standard, version 1.0. - -2560 X.509 Internet Public Key Infrastructure Online Certificate - Status Protocol - OCSP. M. Myers, R. Ankney, A. Malpani, S. Galperin, - C. Adams. June 1999. (Format: TXT=43243 bytes) (Status: PROPOSED - STANDARD) - -2712 Addition of Kerberos Cipher Suites to Transport Layer Security - (TLS). A. Medvinsky, M. Hur. October 1999. (Format: TXT=13763 bytes) - (Status: PROPOSED STANDARD) - -2898 PKCS #5: Password-Based Cryptography Specification Version 2.0. - B. Kaliski. September 2000. (Format: TXT=68692 bytes) (Status: - INFORMATIONAL) - -2986 PKCS #10: Certification Request Syntax Specification Version 1.7. - M. Nystrom, B. Kaliski. November 2000. (Format: TXT=27794 bytes) - (Obsoletes RFC2314) (Status: INFORMATIONAL) - -3174 US Secure Hash Algorithm 1 (SHA1). D. Eastlake 3rd, P. Jones. - September 2001. (Format: TXT=35525 bytes) (Status: INFORMATIONAL) - -3161 Internet X.509 Public Key Infrastructure, Time-Stamp Protocol (TSP) - C. Adams, P. Cain, D. Pinkas, R. Zuccherato. August 2001 - (Status: PROPOSED STANDARD) - -3268 Advanced Encryption Standard (AES) Ciphersuites for Transport - Layer Security (TLS). P. Chown. June 2002. (Format: TXT=13530 bytes) - (Status: PROPOSED STANDARD) - -3279 Algorithms and Identifiers for the Internet X.509 Public Key - Infrastructure Certificate and Certificate Revocation List (CRL) - Profile. L. Bassham, W. Polk, R. Housley. April 2002. (Format: - TXT=53833 bytes) (Status: PROPOSED STANDARD) - -3280 Internet X.509 Public Key Infrastructure Certificate and - Certificate Revocation List (CRL) Profile. R. Housley, W. Polk, W. - Ford, D. Solo. April 2002. (Format: TXT=295556 bytes) (Obsoletes - RFC2459) (Status: PROPOSED STANDARD) - -3447 Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography - Specifications Version 2.1. J. Jonsson, B. Kaliski. February 2003. - (Format: TXT=143173 bytes) (Obsoletes RFC2437) (Status: - INFORMATIONAL) - -3713 A Description of the Camellia Encryption Algorithm. M. Matsui, - J. Nakajima, S. Moriai. April 2004. (Format: TXT=25031 bytes) - (Status: INFORMATIONAL) - -3820 Internet X.509 Public Key Infrastructure (PKI) Proxy Certificate - Profile. S. Tuecke, V. Welch, D. Engert, L. Pearlman, M. Thompson. - June 2004. (Format: TXT=86374 bytes) (Status: PROPOSED STANDARD) - -4132 Addition of Camellia Cipher Suites to Transport Layer Security - (TLS). S. Moriai, A. Kato, M. Kanda. July 2005. (Format: TXT=13590 - bytes) (Status: PROPOSED STANDARD) - -4162 Addition of SEED Cipher Suites to Transport Layer Security (TLS). - H.J. Lee, J.H. Yoon, J.I. Lee. August 2005. (Format: TXT=10578 bytes) - (Status: PROPOSED STANDARD) - -4269 The SEED Encryption Algorithm. H.J. Lee, S.J. Lee, J.H. Yoon, - D.H. Cheon, J.I. Lee. December 2005. (Format: TXT=34390 bytes) - (Obsoletes RFC4009) (Status: INFORMATIONAL) - - -Related: --------- - -These are documents that are close to OpenSSL, for example the -STARTTLS documents. - -1421 Privacy Enhancement for Internet Electronic Mail: Part I: Message - Encryption and Authentication Procedures. J. Linn. February 1993. - (Format: TXT=103894 bytes) (Obsoletes RFC1113) (Status: PROPOSED - STANDARD) - -1422 Privacy Enhancement for Internet Electronic Mail: Part II: - Certificate-Based Key Management. S. Kent. February 1993. (Format: - TXT=86085 bytes) (Obsoletes RFC1114) (Status: PROPOSED STANDARD) - -1423 Privacy Enhancement for Internet Electronic Mail: Part III: - Algorithms, Modes, and Identifiers. D. Balenson. February 1993. - (Format: TXT=33277 bytes) (Obsoletes RFC1115) (Status: PROPOSED - STANDARD) - -1424 Privacy Enhancement for Internet Electronic Mail: Part IV: Key - Certification and Related Services. B. Kaliski. February 1993. - (Format: TXT=17537 bytes) (Status: PROPOSED STANDARD) - -2025 The Simple Public-Key GSS-API Mechanism (SPKM). C. Adams. October - 1996. (Format: TXT=101692 bytes) (Status: PROPOSED STANDARD) - -2510 Internet X.509 Public Key Infrastructure Certificate Management - Protocols. C. Adams, S. Farrell. March 1999. (Format: TXT=158178 - bytes) (Status: PROPOSED STANDARD) - -2511 Internet X.509 Certificate Request Message Format. M. Myers, C. - Adams, D. Solo, D. Kemp. March 1999. (Format: TXT=48278 bytes) - (Status: PROPOSED STANDARD) - -2527 Internet X.509 Public Key Infrastructure Certificate Policy and - Certification Practices Framework. S. Chokhani, W. Ford. March 1999. - (Format: TXT=91860 bytes) (Status: INFORMATIONAL) - -2538 Storing Certificates in the Domain Name System (DNS). D. Eastlake - 3rd, O. Gudmundsson. March 1999. (Format: TXT=19857 bytes) (Status: - PROPOSED STANDARD) - -2539 Storage of Diffie-Hellman Keys in the Domain Name System (DNS). - D. Eastlake 3rd. March 1999. (Format: TXT=21049 bytes) (Status: - PROPOSED STANDARD) - -2559 Internet X.509 Public Key Infrastructure Operational Protocols - - LDAPv2. S. Boeyen, T. Howes, P. Richard. April 1999. (Format: - TXT=22889 bytes) (Updates RFC1778) (Status: PROPOSED STANDARD) - -2585 Internet X.509 Public Key Infrastructure Operational Protocols: - FTP and HTTP. R. Housley, P. Hoffman. May 1999. (Format: TXT=14813 - bytes) (Status: PROPOSED STANDARD) - -2587 Internet X.509 Public Key Infrastructure LDAPv2 Schema. S. - Boeyen, T. Howes, P. Richard. June 1999. (Format: TXT=15102 bytes) - (Status: PROPOSED STANDARD) - -2595 Using TLS with IMAP, POP3 and ACAP. C. Newman. June 1999. - (Format: TXT=32440 bytes) (Status: PROPOSED STANDARD) - -2631 Diffie-Hellman Key Agreement Method. E. Rescorla. June 1999. - (Format: TXT=25932 bytes) (Status: PROPOSED STANDARD) - -2632 S/MIME Version 3 Certificate Handling. B. Ramsdell, Ed.. June - 1999. (Format: TXT=27925 bytes) (Status: PROPOSED STANDARD) - -2716 PPP EAP TLS Authentication Protocol. B. Aboba, D. Simon. October - 1999. (Format: TXT=50108 bytes) (Status: EXPERIMENTAL) - -2773 Encryption using KEA and SKIPJACK. R. Housley, P. Yee, W. Nace. - February 2000. (Format: TXT=20008 bytes) (Updates RFC0959) (Status: - EXPERIMENTAL) - -2797 Certificate Management Messages over CMS. M. Myers, X. Liu, J. - Schaad, J. Weinstein. April 2000. (Format: TXT=103357 bytes) (Status: - PROPOSED STANDARD) - -2817 Upgrading to TLS Within HTTP/1.1. R. Khare, S. Lawrence. May - 2000. (Format: TXT=27598 bytes) (Updates RFC2616) (Status: PROPOSED - STANDARD) - -2818 HTTP Over TLS. E. Rescorla. May 2000. (Format: TXT=15170 bytes) - (Status: INFORMATIONAL) - -2876 Use of the KEA and SKIPJACK Algorithms in CMS. J. Pawling. July - 2000. (Format: TXT=29265 bytes) (Status: INFORMATIONAL) - -2984 Use of the CAST-128 Encryption Algorithm in CMS. C. Adams. - October 2000. (Format: TXT=11591 bytes) (Status: PROPOSED STANDARD) - -2985 PKCS #9: Selected Object Classes and Attribute Types Version 2.0. - M. Nystrom, B. Kaliski. November 2000. (Format: TXT=70703 bytes) - (Status: INFORMATIONAL) - -3029 Internet X.509 Public Key Infrastructure Data Validation and - Certification Server Protocols. C. Adams, P. Sylvester, M. Zolotarev, - R. Zuccherato. February 2001. (Format: TXT=107347 bytes) (Status: - EXPERIMENTAL) - -3039 Internet X.509 Public Key Infrastructure Qualified Certificates - Profile. S. Santesson, W. Polk, P. Barzin, M. Nystrom. January 2001. - (Format: TXT=67619 bytes) (Status: PROPOSED STANDARD) - -3058 Use of the IDEA Encryption Algorithm in CMS. S. Teiwes, P. - Hartmann, D. Kuenzi. February 2001. (Format: TXT=17257 bytes) - (Status: INFORMATIONAL) - -3161 Internet X.509 Public Key Infrastructure Time-Stamp Protocol - (TSP). C. Adams, P. Cain, D. Pinkas, R. Zuccherato. August 2001. - (Format: TXT=54585 bytes) (Status: PROPOSED STANDARD) - -3185 Reuse of CMS Content Encryption Keys. S. Farrell, S. Turner. - October 2001. (Format: TXT=20404 bytes) (Status: PROPOSED STANDARD) - -3207 SMTP Service Extension for Secure SMTP over Transport Layer - Security. P. Hoffman. February 2002. (Format: TXT=18679 bytes) - (Obsoletes RFC2487) (Status: PROPOSED STANDARD) - -3217 Triple-DES and RC2 Key Wrapping. R. Housley. December 2001. - (Format: TXT=19855 bytes) (Status: INFORMATIONAL) - -3274 Compressed Data Content Type for Cryptographic Message Syntax - (CMS). P. Gutmann. June 2002. (Format: TXT=11276 bytes) (Status: - PROPOSED STANDARD) - -3278 Use of Elliptic Curve Cryptography (ECC) Algorithms in - Cryptographic Message Syntax (CMS). S. Blake-Wilson, D. Brown, P. - Lambert. April 2002. (Format: TXT=33779 bytes) (Status: - INFORMATIONAL) - -3281 An Internet Attribute Certificate Profile for Authorization. S. - Farrell, R. Housley. April 2002. (Format: TXT=90580 bytes) (Status: - PROPOSED STANDARD) - -3369 Cryptographic Message Syntax (CMS). R. Housley. August 2002. - (Format: TXT=113975 bytes) (Obsoletes RFC2630, RFC3211) (Status: - PROPOSED STANDARD) - -3370 Cryptographic Message Syntax (CMS) Algorithms. R. Housley. August - 2002. (Format: TXT=51001 bytes) (Obsoletes RFC2630, RFC3211) (Status: - PROPOSED STANDARD) - -3377 Lightweight Directory Access Protocol (v3): Technical - Specification. J. Hodges, R. Morgan. September 2002. (Format: - TXT=9981 bytes) (Updates RFC2251, RFC2252, RFC2253, RFC2254, RFC2255, - RFC2256, RFC2829, RFC2830) (Status: PROPOSED STANDARD) - -3394 Advanced Encryption Standard (AES) Key Wrap Algorithm. J. Schaad, - R. Housley. September 2002. (Format: TXT=73072 bytes) (Status: - INFORMATIONAL) - -3436 Transport Layer Security over Stream Control Transmission - Protocol. A. Jungmaier, E. Rescorla, M. Tuexen. December 2002. - (Format: TXT=16333 bytes) (Status: PROPOSED STANDARD) - -3657 Use of the Camellia Encryption Algorithm in Cryptographic - Message Syntax (CMS). S. Moriai, A. Kato. January 2004. - (Format: TXT=26282 bytes) (Status: PROPOSED STANDARD) - -"Securing FTP with TLS", 01/27/2000, <draft-murray-auth-ftp-ssl-05.txt> - - -To be implemented: ------------------- - -These are documents that describe things that are planed to be -implemented in the hopefully short future. - |