diff options
| author | markm <markm@FreeBSD.org> | 2003-01-28 21:43:22 +0000 |
|---|---|---|
| committer | markm <markm@FreeBSD.org> | 2003-01-28 21:43:22 +0000 |
| commit | aad1d64cb5a8d9b503d9199642363dc1e92d2f9b (patch) | |
| tree | 610a51c6e3965764fb0f1629c1376e2d23afffe8 /crypto/openssl/doc | |
| parent | eba366e36e93f5da8ae5c744eb337c3ef6872641 (diff) | |
| download | FreeBSD-src-aad1d64cb5a8d9b503d9199642363dc1e92d2f9b.zip FreeBSD-src-aad1d64cb5a8d9b503d9199642363dc1e92d2f9b.tar.gz | |
Vendor import of OpenSSL release 0.9.7. This release includes
support for AES and OpenBSD's hardware crypto.
Diffstat (limited to 'crypto/openssl/doc')
134 files changed, 6470 insertions, 786 deletions
diff --git a/crypto/openssl/doc/HOWTO/certificates.txt b/crypto/openssl/doc/HOWTO/certificates.txt new file mode 100644 index 0000000..8804864 --- /dev/null +++ b/crypto/openssl/doc/HOWTO/certificates.txt @@ -0,0 +1,85 @@ +<DRAFT!> + HOWTO certificates + +How you handle certificates depend a great deal on what your role is. +Your role can be one or several of: + + - User of some client software + - User of some server software + - Certificate authority + +This file is for users who wish to get a certificate of their own. +Certificate authorities should read ca.txt. + +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/ssr/ or somewhere else. The name is openssl.cnf, and +is better described in another HOWTO <config.txt?>. If you want to +use a different configuration file, use the argument '-config {file}' +with the command shown below. + + +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' if you want a RSA +private key, or 'openssl gendsa' if you want a DSA private key. More +info on how to handle these commands are found in the manual pages for +those commands or by running them with the argument '-h'. For the +sake of the description in this file, let's assume that the private +key ended up in the file privkey.pem (which is the default in some +cases). + + +Let's start with the most normal way of getting a certificate. Most +often, you want or need to get a certificate from a certificate +authority. To handle that, the certificate authority needs 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) from you. To generate a request, use the +command 'openssl req' 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, that isn't sufficient and you will +have to be more creative. + +When the certificate authority has then done the checks the need to +do (and probably gotten payment from you), they will hand over your +new certificate to you. + + +[fill in on how to create a self-signed 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 yor applications, simply concatenating the certificate and +the key into a new file and using that one should be enough. With +some applications, you don't even have to do that. + + +By now, you have your cetificate and your private key and can start +using the software that depend on it. + +-- +Richard Levitte diff --git a/crypto/openssl/doc/apps/CA.pl.pod b/crypto/openssl/doc/apps/CA.pl.pod index 63cd132..58e0f52 100644 --- a/crypto/openssl/doc/apps/CA.pl.pod +++ b/crypto/openssl/doc/apps/CA.pl.pod @@ -13,6 +13,7 @@ B<CA.pl> [B<-help>] [B<-newcert>] [B<-newreq>] +[B<-newreq-nodes>] [B<-newca>] [B<-xsign>] [B<-sign>] @@ -46,6 +47,10 @@ written to the file "newreq.pem". creates a new certificate request. The private key and request are written to the file "newreq.pem". +=item B<-newreq-nowdes> + +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> diff --git a/crypto/openssl/doc/apps/ca.pod b/crypto/openssl/doc/apps/ca.pod index cea9002..183cd47 100644 --- a/crypto/openssl/doc/apps/ca.pod +++ b/crypto/openssl/doc/apps/ca.pod @@ -13,6 +13,11 @@ B<openssl> B<ca> [B<-name section>] [B<-gencrl>] [B<-revoke file>] +[B<-crl_reason reason>] +[B<-crl_hold instruction>] +[B<-crl_compromise time>] +[B<-crl_CA_compromise time>] +[B<-subj arg>] [B<-crldays days>] [B<-crlhours hours>] [B<-crlexts section>] @@ -33,9 +38,11 @@ B<openssl> B<ca> [B<-spkac file>] [B<-ss_cert file>] [B<-preserveDN>] +[B<-noemailDN>] [B<-batch>] [B<-msie_hack>] [B<-extensions section>] +[B<-extfile section>] =head1 DESCRIPTION @@ -71,7 +78,7 @@ 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<NOTES> +and additional field values to be signed by the CA. See the B<SPKAC FORMAT> section for information on the required format. =item B<-infiles> @@ -109,6 +116,7 @@ the 'ps' utility) this option should be used with caution. 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. @@ -159,6 +167,15 @@ 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 @@ -167,9 +184,16 @@ 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. 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. +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. + +=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). =back @@ -194,6 +218,39 @@ the number of hours before the next CRL is due. a filename containing a certificate to revoke. +=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<-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<-crlexts section> the section of the configuration file containing CRL extensions to @@ -311,6 +368,12 @@ the same as B<-crlexts>. 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> @@ -320,6 +383,37 @@ the same as B<-msie_hack> the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section for more information. +=item B<nameopt>, B<certopt> + +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<default_ca> 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 @@ -409,6 +503,11 @@ A sample configuration file with the relevant sections for B<ca>: default_md = md5 # md to use policy = policy_any # default policy + email_in_dn = no # Don't add the email into cert DN + + nameopt = default_ca # Subject name display option + certopt = default_ca # Certificate display option + copy_extensions = none # Don't copy extensions from request [ policy_any ] countryName = supplied @@ -418,18 +517,6 @@ A sample configuration file with the relevant sections for B<ca>: commonName = supplied emailAddress = optional -=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 be 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. - =head1 FILES Note: the location of all files can change either by compile time options, @@ -459,9 +546,6 @@ 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. -CRL entry extensions cannot currently be created: only CRL extensions -can be added. - V2 CRL features like delta CRL support and CRL numbers are not currently supported. @@ -474,10 +558,6 @@ 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. -Certificate request extensions are ignored: some kind of "policy" should -be included to use certain static extensions and certain extensions -from the request. - It is not possible to certify two certificates with the same DN: this is a side effect of how the text database is indexed and it cannot easily be fixed without introducing other problems. Some S/MIME clients can use @@ -490,13 +570,49 @@ exposed at either a command or interface level so a more friendly utility 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 but -the extra fields are not displayed when the user is asked to certify -a request. The behaviour should be more friendly and configurable. +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)>, diff --git a/crypto/openssl/doc/apps/ciphers.pod b/crypto/openssl/doc/apps/ciphers.pod index 2107761..81a2c43 100644 --- a/crypto/openssl/doc/apps/ciphers.pod +++ b/crypto/openssl/doc/apps/ciphers.pod @@ -108,10 +108,20 @@ the default cipher list. This is determined at compile time and is normally B<ALL:!ADH:RC4+RSA:+SSLv2:@STRENGTH>. This must be the first cipher string specified. +=item B<COMPLEMENTOFDEFAULT> + +the ciphers included in B<ALL>, but not enabled by default. Currently +this is B<ADH>. Note that this rule does not cover B<eNULL>, which is +not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary). + =item B<ALL> all ciphers suites except the B<eNULL> ciphers which must be explicitly enabled. +=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 @@ -193,6 +203,10 @@ cipher suites using DH, including anonymous DH. anonymous DH cipher suites. +=item B<AES> + +cipher suites using AES. + =item B<3DES> cipher suites using triple DES. @@ -226,7 +240,9 @@ cipher suites using SHA1. =head1 CIPHER SUITE NAMES The following lists give the SSL or TLS cipher suites names from the -relevant specification and their OpenSSL equivalents. +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. @@ -296,6 +312,24 @@ relevant specification and their OpenSSL equivalents. 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 Additional Export 1024 and other cipher suites Note: these ciphers can also be used in SSL v3. @@ -339,8 +373,22 @@ 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 were +added in version 0.9.7. + =cut diff --git a/crypto/openssl/doc/apps/enc.pod b/crypto/openssl/doc/apps/enc.pod index a68ddca..ddf0816 100644 --- a/crypto/openssl/doc/apps/enc.pod +++ b/crypto/openssl/doc/apps/enc.pod @@ -21,6 +21,7 @@ B<openssl enc -ciphername> [B<-p>] [B<-P>] [B<-bufsize number>] +[B<-nopad>] [B<-debug>] =head1 DESCRIPTION @@ -122,6 +123,10 @@ or decryption. set the buffer size for I/O +=item B<-nopad> + +disable standard block padding + =item B<-debug> debug the BIOs used for I/O. @@ -150,11 +155,14 @@ 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 use PKCS#5 padding also known as standard block +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. @@ -256,8 +264,8 @@ 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. -Like the EVP library 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. +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/crypto/openssl/doc/apps/ocsp.pod b/crypto/openssl/doc/apps/ocsp.pod new file mode 100644 index 0000000..da201b9 --- /dev/null +++ b/crypto/openssl/doc/apps/ocsp.pod @@ -0,0 +1,348 @@ +=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<-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 responder_url>] +[B<-host host:n>] +[B<-path>] +[B<-CApath file>] +[B<-CAfile file>] +[B<-VAfile file>] +[B<-verify_certs file>] +[B<-noverify>] +[B<-trust_other>] +[B<-no_intern>] +[B<-no_sig_verify>] +[B<-no_cert_verify>] +[B<-no_chain>] +[B<-no_cert_checks>] +[B<-validity_period nsec>] +[B<-status_age nsec>] + +=head1 DESCRIPTION + +B<WARNING: this documentation is preliminary and subject to change.> + +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. + +=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<-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<-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<-verify_certs 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_certs> 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_certs> 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_certs> or B<-VAfile> options. + +=item B<-no_sig_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_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. + +=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 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 diff --git a/crypto/openssl/doc/apps/openssl.pod b/crypto/openssl/doc/apps/openssl.pod index e3c79a4..07dd80e 100644 --- a/crypto/openssl/doc/apps/openssl.pod +++ b/crypto/openssl/doc/apps/openssl.pod @@ -121,6 +121,10 @@ Generation of DSA Parameters. Generation of RSA Parameters. +=item L<B<ocsp>|ocsp(1)> + +Online Certificate Status Protocol utility. + =item L<B<passwd>|passwd(1)> Generation of hashed passwords. diff --git a/crypto/openssl/doc/apps/passwd.pod b/crypto/openssl/doc/apps/passwd.pod index 6e09894..f449825 100644 --- a/crypto/openssl/doc/apps/passwd.pod +++ b/crypto/openssl/doc/apps/passwd.pod @@ -13,6 +13,7 @@ B<openssl passwd> [B<-salt> I<string>] [B<-in> I<file>] [B<-stdin>] +[B<-noverify>] [B<-quiet>] [B<-table>] {I<password>} @@ -22,7 +23,7 @@ B<openssl passwd> 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>, and from the command line otherwise. +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. @@ -45,6 +46,7 @@ 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> @@ -54,6 +56,10 @@ Read passwords from I<file>. 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. @@ -69,7 +75,7 @@ to each password hash. B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>. -B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$8XJIcl6ZXqBMCK0qFevqT1>. +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>. diff --git a/crypto/openssl/doc/apps/pkcs12.pod b/crypto/openssl/doc/apps/pkcs12.pod index 7e0307d..7d84146 100644 --- a/crypto/openssl/doc/apps/pkcs12.pod +++ b/crypto/openssl/doc/apps/pkcs12.pod @@ -262,7 +262,7 @@ 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 -outputing the certificate corresponding to the private key. If the CA +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. diff --git a/crypto/openssl/doc/apps/pkcs7.pod b/crypto/openssl/doc/apps/pkcs7.pod index 4e9bd6e..9871c0e 100644 --- a/crypto/openssl/doc/apps/pkcs7.pod +++ b/crypto/openssl/doc/apps/pkcs7.pod @@ -78,7 +78,7 @@ The PEM PKCS#7 format uses the header and footer lines: -----BEGIN PKCS7----- -----END PKCS7----- -For compatability with some CAs it will also accept: +For compatibility with some CAs it will also accept: -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- diff --git a/crypto/openssl/doc/apps/rand.pod b/crypto/openssl/doc/apps/rand.pod index cbf8768..75745ca 100644 --- a/crypto/openssl/doc/apps/rand.pod +++ b/crypto/openssl/doc/apps/rand.pod @@ -15,7 +15,7 @@ I<num> =head1 DESCRIPTION The B<rand> command outputs I<num> pseudo-random bytes after seeding -the random number generater once. As in other B<openssl> command +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 diff --git a/crypto/openssl/doc/apps/req.pod b/crypto/openssl/doc/apps/req.pod index a3f54f4..7a3b6bb 100644 --- a/crypto/openssl/doc/apps/req.pod +++ b/crypto/openssl/doc/apps/req.pod @@ -3,7 +3,7 @@ =head1 NAME -req - PKCS#10 certificate and certificate generating utility. +req - PKCS#10 certificate request and certificate generating utility. =head1 SYNOPSIS @@ -15,6 +15,7 @@ B<openssl> B<req> [B<-out filename>] [B<-passout arg>] [B<-text>] +[B<-pubkey>] [B<-noout>] [B<-verify>] [B<-modulus>] @@ -28,12 +29,18 @@ B<openssl> B<req> [B<-keyout filename>] [B<-[md5|sha1|md2|mdc2]>] [B<-config filename>] +[B<-subj arg>] [B<-x509>] [B<-days n>] +[B<-set_serial n>] [B<-asn1-kludge>] [B<-newhdr>] [B<-extensions section>] [B<-reqexts section>] +[B<-utf8>] +[B<-nameopt>] +[B<-batch>] +[B<-verbose>] =head1 DESCRIPTION @@ -82,6 +89,10 @@ see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. prints out the certificate request in text form. +=item B<-pubkey> + +outputs the public key. + =item B<-noout> this option prevents output of the encoded version of the request. @@ -154,18 +165,33 @@ 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<-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. +(if any) are specified in the configuration file. Unless specified +using the B<set_serial> option B<0> 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> @@ -176,6 +202,20 @@ 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<-asn1-kludge> by default the B<req> command outputs certificate requests containing @@ -196,6 +236,14 @@ It should be noted that very few CAs still require the use of this option. Adds the word B<NEW> to the PEM file header and footer lines on the outputed 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. + =back =head1 CONFIGURATION FILE FORMAT @@ -292,6 +340,13 @@ 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 @@ -457,13 +512,13 @@ Sample configuration containing all field values: The header and footer lines in the B<PEM> format are normally: - -----BEGIN CERTIFICATE REQUEST---- - -----END CERTIFICATE REQUEST---- + -----BEGIN CERTIFICATE REQUEST----- + -----END CERTIFICATE REQUEST----- some software (some versions of Netscape certificate server) instead needs: - -----BEGIN NEW CERTIFICATE REQUEST---- - -----END NEW CERTIFICATE REQUEST---- + -----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. diff --git a/crypto/openssl/doc/apps/rsa.pod b/crypto/openssl/doc/apps/rsa.pod index f0e613e..ef74f1a 100644 --- a/crypto/openssl/doc/apps/rsa.pod +++ b/crypto/openssl/doc/apps/rsa.pod @@ -136,7 +136,7 @@ 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 thse with the utility view the file with a binary editor +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 diff --git a/crypto/openssl/doc/apps/s_client.pod b/crypto/openssl/doc/apps/s_client.pod index f596ec7..7fca9cb 100644 --- a/crypto/openssl/doc/apps/s_client.pod +++ b/crypto/openssl/doc/apps/s_client.pod @@ -18,6 +18,7 @@ B<openssl> B<s_client> [B<-pause>] [B<-showcerts>] [B<-debug>] +[B<-msg>] [B<-nbio_test>] [B<-state>] [B<-nbio>] @@ -32,6 +33,7 @@ B<openssl> B<s_client> [B<-no_tls1>] [B<-bugs>] [B<-cipher cipherlist>] +[B<-engine id>] [B<-rand file(s)>] =head1 DESCRIPTION @@ -111,6 +113,10 @@ prints out the SSL session states. 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 @@ -131,7 +137,7 @@ input. =item B<-quiet> -inhibit printing of session and certificate information. This implicitely +inhibit printing of session and certificate information. This implicitly turns on B<-ign_eof> as well. =item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> @@ -157,6 +163,13 @@ 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<-engine id> + +specifying an engine (by it's 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 @@ -172,7 +185,7 @@ all others. 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 renegociated if the line begins with an +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. diff --git a/crypto/openssl/doc/apps/s_server.pod b/crypto/openssl/doc/apps/s_server.pod index 23a073a..4b1e426 100644 --- a/crypto/openssl/doc/apps/s_server.pod +++ b/crypto/openssl/doc/apps/s_server.pod @@ -21,6 +21,7 @@ B<openssl> B<s_server> [B<-nbio_test>] [B<-crlf>] [B<-debug>] +[B<-msg>] [B<-state>] [B<-CApath directory>] [B<-CAfile filename>] @@ -39,6 +40,8 @@ B<openssl> B<s_server> [B<-hack>] [B<-www>] [B<-WWW>] +[B<-HTTP>] +[B<-engine id>] [B<-rand file(s)>] =head1 DESCRIPTION @@ -134,6 +137,10 @@ prints out the SSL session states. 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 @@ -187,6 +194,21 @@ 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 it's 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<-rand file(s)> a file or files containing random data used to seed the random number diff --git a/crypto/openssl/doc/apps/smime.pod b/crypto/openssl/doc/apps/smime.pod index fa5d23e..2453dd2 100644 --- a/crypto/openssl/doc/apps/smime.pod +++ b/crypto/openssl/doc/apps/smime.pod @@ -340,8 +340,8 @@ 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---- + -----BEGIN PKCS7----- + -----END PKCS7----- and using the command, diff --git a/crypto/openssl/doc/apps/speed.pod b/crypto/openssl/doc/apps/speed.pod index 77560f1..0dcdba8 100644 --- a/crypto/openssl/doc/apps/speed.pod +++ b/crypto/openssl/doc/apps/speed.pod @@ -7,6 +7,7 @@ speed - test library performance =head1 SYNOPSIS B<openssl speed> +[B<-engine id>] [B<md2>] [B<mdc2>] [B<md5>] @@ -39,7 +40,20 @@ This command is used to test the performance of cryptographic algorithms. =head1 OPTIONS +=over 4 + +=item B<-engine id> + +specifying an engine (by it's 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/crypto/openssl/doc/apps/version.pod b/crypto/openssl/doc/apps/version.pod index 5d261a6..e00324c 100644 --- a/crypto/openssl/doc/apps/version.pod +++ b/crypto/openssl/doc/apps/version.pod @@ -46,6 +46,10 @@ compilation flags. platform setting. +=item B<-d> + +OPENSSLDIR setting. + =back =head1 NOTES @@ -53,4 +57,8 @@ platform setting. 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/crypto/openssl/doc/apps/x509.pod b/crypto/openssl/doc/apps/x509.pod index 84f76cb..674bfd1 100644 --- a/crypto/openssl/doc/apps/x509.pod +++ b/crypto/openssl/doc/apps/x509.pod @@ -36,6 +36,7 @@ B<openssl> B<x509> [B<-addreject arg>] [B<-setalias arg>] [B<-days arg>] +[B<-set_serial n>] [B<-signkey filename>] [B<-x509toreq>] [B<-req>] @@ -60,8 +61,9 @@ certificate trust settings. Since there are a large number of options they will split up into various sections. +=head1 OPTIONS -=head1 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS +=head2 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS =over 4 @@ -99,10 +101,10 @@ this option has no effect: SHA1 is always used with DSA keys. =back -=head1 DISPLAY OPTIONS +=head2 DISPLAY OPTIONS Note: the B<-alias> and B<-purpose> options are also display options -but are described in the B<TRUST OPTIONS> section. +but are described in the B<TRUST SETTINGS> section. =over 4 @@ -112,6 +114,13 @@ 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. @@ -141,9 +150,10 @@ outputs the issuer name. =item B<-nameopt option> -option which determine how the subject or issuer names are displayed. This -option may be used more than once to set multiple options. See the B<NAME -OPTIONS> section for more information. +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> @@ -163,7 +173,8 @@ prints out the start and expiry dates of a certificate. =item B<-fingerprint> -prints out the digest of the DER encoded version of the whole certificate. +prints out the digest of the DER encoded version of the whole certificate +(see digest options). =item B<-C> @@ -171,7 +182,7 @@ this outputs the certificate in the form of a C source file. =back -=head1 TRUST SETTINGS +=head2 TRUST SETTINGS Please note these options are currently experimental and may well change. @@ -242,7 +253,7 @@ EXTENSIONS> section. =back -=head1 SIGNING OPTIONS +=head2 SIGNING OPTIONS The B<x509> utility can be used to sign certificates and requests: it can thus behave like a "mini CA". @@ -292,6 +303,16 @@ is used to pass the required private key. 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 @@ -321,7 +342,7 @@ 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 filename> +=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 @@ -342,7 +363,7 @@ specified then the extensions should either be contained in the unnamed =back -=head1 NAME OPTIONS +=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" @@ -372,12 +393,12 @@ options. =item B<multiline> a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>, -B<spc_eq> and B<lname>. +B<spc_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 beginnging of a string +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> @@ -431,7 +452,7 @@ B<#XXXX...> format. 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 repesents a single character. +as though each content octet represents a single character. =item B<dump_all> @@ -467,6 +488,11 @@ not display the field at all. B<sname> uses the "short name" 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<spc_eq> places spaces round the B<=> character which follows the field @@ -474,6 +500,85 @@ 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>, +B<no_version>, B<no_sigdump> and B<no_signame>. + +=back + =head1 EXAMPLES Note: in these examples the '\' means the example should be all on one @@ -498,7 +603,7 @@ Display the certificate subject name in RFC2253 form: Display the certificate subject name in oneline form on a terminal supporting UTF8: - openssl x509 -in cert.pem -noout -subject -nameopt oneline -nameopt -escmsb + openssl x509 -in cert.pem -noout -subject -nameopt oneline,-escmsb Display the certificate MD5 fingerprint: @@ -539,18 +644,18 @@ Set a certificate to be trusted for SSL client use and change set its alias to The PEM format uses the header and footer lines: - -----BEGIN CERTIFICATE---- - -----END CERTIFICATE---- + -----BEGIN CERTIFICATE----- + -----END CERTIFICATE----- it will also handle files containing: - -----BEGIN X509 CERTIFICATE---- - -----END X509 CERTIFICATE---- + -----BEGIN X509 CERTIFICATE----- + -----END X509 CERTIFICATE----- Trusted certificates have the lines - -----BEGIN TRUSTED CERTIFICATE---- - -----END TRUSTED CERTIFICATE---- + -----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 diff --git a/crypto/openssl/doc/c-indentation.el b/crypto/openssl/doc/c-indentation.el index 48ca3cf..cbf01cb 100644 --- a/crypto/openssl/doc/c-indentation.el +++ b/crypto/openssl/doc/c-indentation.el @@ -13,12 +13,10 @@ ; ; 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. -; The style defined below does not indent them at all. -; To insert tabs manually, prefix them with ^Q (the "quoted-insert" -; command of Emacs). If you know a solution to this problem -; or find other problems with this indentation style definition, -; please send e-mail to bodo@openssl.org. +; 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) diff --git a/crypto/openssl/doc/crypto/ASN1_OBJECT_new.pod b/crypto/openssl/doc/crypto/ASN1_OBJECT_new.pod new file mode 100644 index 0000000..51679bf --- /dev/null +++ b/crypto/openssl/doc/crypto/ASN1_OBJECT_new.pod @@ -0,0 +1,43 @@ +=pod + +=head1 NAME + +ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions + +=head1 SYNOPSIS + + 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/crypto/openssl/doc/crypto/ASN1_STRING_length.pod b/crypto/openssl/doc/crypto/ASN1_STRING_length.pod new file mode 100644 index 0000000..c4ec693 --- /dev/null +++ b/crypto/openssl/doc/crypto/ASN1_STRING_length.pod @@ -0,0 +1,81 @@ +=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 utility functions + +=head1 SYNOPSIS + + 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/crypto/openssl/doc/crypto/ASN1_STRING_new.pod b/crypto/openssl/doc/crypto/ASN1_STRING_new.pod new file mode 100644 index 0000000..5b1bbb7 --- /dev/null +++ b/crypto/openssl/doc/crypto/ASN1_STRING_new.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free - +ASN1_STRING allocation functions + +=head1 SYNOPSIS + + 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/crypto/openssl/doc/crypto/ASN1_STRING_print_ex.pod b/crypto/openssl/doc/crypto/ASN1_STRING_print_ex.pod new file mode 100644 index 0000000..fbf9a1f --- /dev/null +++ b/crypto/openssl/doc/crypto/ASN1_STRING_print_ex.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - 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_STRFLAGS_RFC2253> is +suitable, or on UTF8 terminals B<ASN1_STRFLAGS_RFC2253 & ~ASN1_STRFLAGS_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 "\WXXXX" is used +using exactly four characters for the hex representation. If it is 32 bits then +"\UXXXXXXXX" 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_STRFLAGS_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/crypto/openssl/doc/crypto/BIO_f_md.pod b/crypto/openssl/doc/crypto/BIO_f_md.pod index c32504d..0d24083 100644 --- a/crypto/openssl/doc/crypto/BIO_f_md.pod +++ b/crypto/openssl/doc/crypto/BIO_f_md.pod @@ -28,7 +28,7 @@ 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() reinitializes a digest BIO. +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 diff --git a/crypto/openssl/doc/crypto/BIO_s_accept.pod b/crypto/openssl/doc/crypto/BIO_s_accept.pod index c49da7f..7b63e46 100644 --- a/crypto/openssl/doc/crypto/BIO_s_accept.pod +++ b/crypto/openssl/doc/crypto/BIO_s_accept.pod @@ -2,7 +2,7 @@ =head1 NAME -BIO_s_accept, BIO_set_nbio, BIO_set_accept_port, BIO_get_accept_port, +BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO @@ -10,31 +10,31 @@ BIO_get_bind_mode, BIO_do_accept - accept BIO #include <openssl/bio.h> - BIO_METHOD * BIO_s_accept(void); + BIO_METHOD *BIO_s_accept(void); - #define BIO_set_accept_port(b,name) BIO_ctrl(b,BIO_C_SET_ACCEPT,0,(char *)name) - #define BIO_get_accept_port(b) BIO_ptr_ctrl(b,BIO_C_GET_ACCEPT,0) + long BIO_set_accept_port(BIO *b, char *name); + char *BIO_get_accept_port(BIO *b); BIO *BIO_new_accept(char *host_port); - #define BIO_set_nbio_accept(b,n) BIO_ctrl(b,BIO_C_SET_ACCEPT,1,(n)?"a":NULL) - #define BIO_set_accept_bios(b,bio) BIO_ctrl(b,BIO_C_SET_ACCEPT,2,(char *)bio) + long BIO_set_nbio_accept(BIO *b, int n); + long BIO_set_accept_bios(BIO *b, char *bio); - #define BIO_set_bind_mode(b,mode) BIO_ctrl(b,BIO_C_SET_BIND_MODE,mode,NULL) - #define BIO_get_bind_mode(b,mode) BIO_ctrl(b,BIO_C_GET_BIND_MODE,0,NULL) + 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 - #define BIO_do_accept(b) BIO_do_handshake(b) + int BIO_do_accept(BIO *b); =head1 DESCRIPTION BIO_s_accept() returns the accept BIO method. This is a wrapper round the platform's TCP/IP socket accept routines. -Using accept BIOs TCP/IP connections can be accepted and data +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. @@ -92,7 +92,7 @@ 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. +connection, or request a retry in non blocking mode. =head1 NOTES @@ -130,6 +130,17 @@ 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 diff --git a/crypto/openssl/doc/crypto/BIO_s_bio.pod b/crypto/openssl/doc/crypto/BIO_s_bio.pod index 95ae802..8d0a55a 100644 --- a/crypto/openssl/doc/crypto/BIO_s_bio.pod +++ b/crypto/openssl/doc/crypto/BIO_s_bio.pod @@ -76,7 +76,9 @@ 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. +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 @@ -118,9 +120,59 @@ 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! +=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 -TBA +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 diff --git a/crypto/openssl/doc/crypto/BIO_s_connect.pod b/crypto/openssl/doc/crypto/BIO_s_connect.pod index fe1aa67..bcf7d8d 100644 --- a/crypto/openssl/doc/crypto/BIO_s_connect.pod +++ b/crypto/openssl/doc/crypto/BIO_s_connect.pod @@ -13,25 +13,27 @@ BIO_set_nbio, BIO_do_connect - connect BIO BIO_METHOD * BIO_s_connect(void); - #define BIO_set_conn_hostname(b,name) BIO_ctrl(b,BIO_C_SET_CONNECT,0,(char *)name) - #define BIO_set_conn_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,1,(char *)port) - #define BIO_set_conn_ip(b,ip) BIO_ctrl(b,BIO_C_SET_CONNECT,2,(char *)ip) - #define BIO_set_conn_int_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,3,(char *)port) - #define BIO_get_conn_hostname(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,0) - #define BIO_get_conn_port(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,1) - #define BIO_get_conn_ip(b,ip) BIO_ptr_ctrl(b,BIO_C_SET_CONNECT,2) - #define BIO_get_conn_int_port(b,port) BIO_int_ctrl(b,BIO_C_SET_CONNECT,3,port) + BIO *BIO_new_connect(char *name); - #define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL) + 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, dummy); + long BIO_get_conn_int_port(BIO *b, int port); - #define BIO_do_connect(b) BIO_do_handshake(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 +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. @@ -54,7 +56,7 @@ 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 +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". @@ -87,6 +89,9 @@ 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 @@ -123,6 +128,11 @@ 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. diff --git a/crypto/openssl/doc/crypto/BIO_s_socket.pod b/crypto/openssl/doc/crypto/BIO_s_socket.pod index 2531851..1c8d3a9 100644 --- a/crypto/openssl/doc/crypto/BIO_s_socket.pod +++ b/crypto/openssl/doc/crypto/BIO_s_socket.pod @@ -8,10 +8,10 @@ BIO_s_socket, BIO_new_socket - socket BIO #include <openssl/bio.h> - BIO_METHOD * BIO_s_socket(void); + BIO_METHOD *BIO_s_socket(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) + 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); @@ -27,10 +27,10 @@ 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<c>. +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 *). +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>. @@ -44,6 +44,8 @@ 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. diff --git a/crypto/openssl/doc/crypto/BN_CTX_new.pod b/crypto/openssl/doc/crypto/BN_CTX_new.pod index c94d8c6..ad8d07d 100644 --- a/crypto/openssl/doc/crypto/BN_CTX_new.pod +++ b/crypto/openssl/doc/crypto/BN_CTX_new.pod @@ -42,7 +42,7 @@ BN_CTX_init() and BN_CTX_free() have no return values. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_add(3)|BN_add(3)>, +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 diff --git a/crypto/openssl/doc/crypto/BN_add.pod b/crypto/openssl/doc/crypto/BN_add.pod index 0541d45..88c7a79 100644 --- a/crypto/openssl/doc/crypto/BN_add.pod +++ b/crypto/openssl/doc/crypto/BN_add.pod @@ -2,8 +2,9 @@ =head1 NAME -BN_add, BN_sub, BN_mul, BN_div, BN_sqr, BN_mod, BN_mod_mul, BN_exp, -BN_mod_exp, BN_gcd - arithmetic operations on BIGNUMs +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 @@ -15,16 +16,26 @@ BN_mod_exp, BN_gcd - arithmetic operations on BIGNUMs 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_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); - int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, + 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, @@ -34,45 +45,59 @@ BN_mod_exp, BN_gcd - arithmetic operations on BIGNUMs =head1 DESCRIPTION -BN_add() adds B<a> and B<b> and places the result in B<r> (C<r=a+b>). -B<r> may be the same B<BIGNUM> as B<a> or B<b>. +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 B<b> from B<a> and places the result in B<r> (C<r=a-b>). +BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>). -BN_mul() multiplies B<a> and B<b> and places the result in B<r> (C<r=a*b>). -B<r> may be the same B<BIGNUM> as B<a> or B<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_div() divides B<a> by B<d> and places the result in B<dv> and the -remainder in B<rem> (C<dv=a/d, rem=a%d>). Either of B<dv> and B<rem> may -be NULL, in which case the respective value is not returned. +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_sqr() takes the square of B<a> and places the result in B<r> -(C<r=a^2>). B<r> and B<a> may be the same B<BIGNUM>. -This function is faster than BN_mul(r,a,a). +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() find the remainder of B<a> divided by B<m> and places it in -B<rem> (C<rem=a%m>). +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_mul() multiplies B<a> by B<b> and finds the remainder when -divided by B<m> (C<r=(a*b)%m>). B<r> may be the same B<BIGNUM> as B<a> -or B<b>. For a more efficient algorithm, see -L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>; for repeated -computations using the same modulus, see 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 B<a> to the B<p>-th power and places the result in B<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 B<a> to the B<p>-th power modulo B<m> (C<r=a^p % +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 B<a> and B<b> and -places the result in B<r>. B<r> may be the same B<BIGNUM> as B<a> or -B<b>. +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, B<ctx> is a previously allocated B<BN_CTX> used for +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 @@ -86,14 +111,16 @@ 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(3)|err(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, +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_div(), BN_sqr(), BN_mod(), BN_mod_mul(), +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 B<ctx> argument to BN_mul() was added in SSLeay +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/crypto/openssl/doc/crypto/BN_add_word.pod b/crypto/openssl/doc/crypto/BN_add_word.pod index 66bedfb..94244ad 100644 --- a/crypto/openssl/doc/crypto/BN_add_word.pod +++ b/crypto/openssl/doc/crypto/BN_add_word.pod @@ -46,7 +46,7 @@ BN_mod_word() and BN_div_word() return B<a>%B<w>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_add(3)|BN_add(3)> +L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/BN_bn2bin.pod b/crypto/openssl/doc/crypto/BN_bn2bin.pod index b62d1af..a4b17ca 100644 --- a/crypto/openssl/doc/crypto/BN_bn2bin.pod +++ b/crypto/openssl/doc/crypto/BN_bn2bin.pod @@ -80,7 +80,7 @@ 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(3)|err(3)>, L<BN_zero(3)|BN_zero(3)>, +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)> diff --git a/crypto/openssl/doc/crypto/BN_copy.pod b/crypto/openssl/doc/crypto/BN_copy.pod index 8ad25e7..388dd7d 100644 --- a/crypto/openssl/doc/crypto/BN_copy.pod +++ b/crypto/openssl/doc/crypto/BN_copy.pod @@ -25,7 +25,7 @@ by L<ERR_get_error(3)|ERR_get_error(3)>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<err(3)|err(3)> +L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/BN_generate_prime.pod b/crypto/openssl/doc/crypto/BN_generate_prime.pod index 638f651..6ea2379 100644 --- a/crypto/openssl/doc/crypto/BN_generate_prime.pod +++ b/crypto/openssl/doc/crypto/BN_generate_prime.pod @@ -90,7 +90,7 @@ 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(3)|err(3)>, L<rand(3)|rand(3)> +L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/BN_mod_inverse.pod b/crypto/openssl/doc/crypto/BN_mod_inverse.pod index 49e62da..3ea3975 100644 --- a/crypto/openssl/doc/crypto/BN_mod_inverse.pod +++ b/crypto/openssl/doc/crypto/BN_mod_inverse.pod @@ -27,7 +27,7 @@ NULL on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_err =head1 SEE ALSO -L<bn(3)|bn(3)>, L<err(3)|err(3)>, L<BN_add(3)|BN_add(3)> +L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/BN_mod_mul_montgomery.pod b/crypto/openssl/doc/crypto/BN_mod_mul_montgomery.pod index 0b8ab51..6b16351 100644 --- a/crypto/openssl/doc/crypto/BN_mod_mul_montgomery.pod +++ b/crypto/openssl/doc/crypto/BN_mod_mul_montgomery.pod @@ -36,22 +36,23 @@ 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 B<mont> structure from the modulus B<m> +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> B<from> to B<to>. +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(B<a>,B<b>):=B<a>*B<b>*R^-1 and places -the result in B<r>. +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 B<r> = B<a>*R^-1. +BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1. -BN_to_montgomery() computes Mont(B<a>,R^2), i.e. B<a>*R. +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, B<ctx> is a previously allocated B<BN_CTX> used for +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: @@ -79,9 +80,14 @@ 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(3)|err(3)>, L<BN_add(3)|BN_add(3)>, +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 diff --git a/crypto/openssl/doc/crypto/BN_mod_mul_reciprocal.pod b/crypto/openssl/doc/crypto/BN_mod_mul_reciprocal.pod index a28925f..74a216d 100644 --- a/crypto/openssl/doc/crypto/BN_mod_mul_reciprocal.pod +++ b/crypto/openssl/doc/crypto/BN_mod_mul_reciprocal.pod @@ -69,7 +69,7 @@ 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(3)|err(3)>, L<BN_add(3)|BN_add(3)>, +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 diff --git a/crypto/openssl/doc/crypto/BN_new.pod b/crypto/openssl/doc/crypto/BN_new.pod index c1394ff..3033789 100644 --- a/crypto/openssl/doc/crypto/BN_new.pod +++ b/crypto/openssl/doc/crypto/BN_new.pod @@ -42,7 +42,7 @@ values. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<err(3)|err(3)> +L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/BN_rand.pod b/crypto/openssl/doc/crypto/BN_rand.pod index 9cec238..81f93c2 100644 --- a/crypto/openssl/doc/crypto/BN_rand.pod +++ b/crypto/openssl/doc/crypto/BN_rand.pod @@ -45,7 +45,7 @@ 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(3)|err(3)>, L<rand(3)|rand(3)>, +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 diff --git a/crypto/openssl/doc/crypto/BN_swap.pod b/crypto/openssl/doc/crypto/BN_swap.pod new file mode 100644 index 0000000..79efaa1 --- /dev/null +++ b/crypto/openssl/doc/crypto/BN_swap.pod @@ -0,0 +1,23 @@ +=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/crypto/openssl/doc/crypto/BN_zero.pod b/crypto/openssl/doc/crypto/BN_zero.pod index 2f33876..b555ec3 100644 --- a/crypto/openssl/doc/crypto/BN_zero.pod +++ b/crypto/openssl/doc/crypto/BN_zero.pod @@ -12,7 +12,7 @@ operations int BN_zero(BIGNUM *a); int BN_one(BIGNUM *a); - BIGNUM *BN_value_one(void); + const BIGNUM *BN_value_one(void); int BN_set_word(BIGNUM *a, unsigned long w); unsigned long BN_get_word(BIGNUM *a); @@ -53,4 +53,7 @@ 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/crypto/openssl/doc/crypto/DH_generate_key.pod b/crypto/openssl/doc/crypto/DH_generate_key.pod index 920995b..81f09fd 100644 --- a/crypto/openssl/doc/crypto/DH_generate_key.pod +++ b/crypto/openssl/doc/crypto/DH_generate_key.pod @@ -40,7 +40,7 @@ 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(3)|err(3)>, L<rand(3)|rand(3)>, L<DH_size(3)|DH_size(3)> +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 diff --git a/crypto/openssl/doc/crypto/DH_generate_parameters.pod b/crypto/openssl/doc/crypto/DH_generate_parameters.pod index a7d0c75..9081e9e 100644 --- a/crypto/openssl/doc/crypto/DH_generate_parameters.pod +++ b/crypto/openssl/doc/crypto/DH_generate_parameters.pod @@ -59,7 +59,8 @@ a usable generator. =head1 SEE ALSO -L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<DH_free(3)|DH_free(3)> +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 diff --git a/crypto/openssl/doc/crypto/DH_new.pod b/crypto/openssl/doc/crypto/DH_new.pod index 64624b9..60c9300 100644 --- a/crypto/openssl/doc/crypto/DH_new.pod +++ b/crypto/openssl/doc/crypto/DH_new.pod @@ -29,7 +29,7 @@ DH_free() returns no value. =head1 SEE ALSO -L<dh(3)|dh(3)>, L<err(3)|err(3)>, +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)> diff --git a/crypto/openssl/doc/crypto/DH_set_method.pod b/crypto/openssl/doc/crypto/DH_set_method.pod index b9a61d5..73261fc 100644 --- a/crypto/openssl/doc/crypto/DH_set_method.pod +++ b/crypto/openssl/doc/crypto/DH_set_method.pod @@ -2,43 +2,55 @@ =head1 NAME -DH_set_default_method, DH_get_default_method, DH_set_method, -DH_new_method, DH_OpenSSL - select DH method +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(DH_METHOD *meth); + void DH_set_default_method(const DH_METHOD *meth); - DH_METHOD *DH_get_default_method(void); + const DH_METHOD *DH_get_default_method(void); - DH_METHOD *DH_set_method(DH *dh, DH_METHOD *meth); + int DH_set_method(DH *dh, const DH_METHOD *meth); - DH *DH_new_method(DH_METHOD *meth); + DH *DH_new_method(ENGINE *engine); - DH_METHOD *DH_OpenSSL(void); + 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. - -Initially, the default is to use the OpenSSL internal implementation. -DH_OpenSSL() returns a pointer to that method. - -DH_set_default_method() makes B<meth> the default method for all B<DH> -structures created later. - -DH_get_default_method() returns a pointer to the current default -method. - -DH_set_method() selects B<meth> for all operations using the structure B<dh>. - -DH_new_method() allocates and initializes a B<DH> structure so that -B<method> will be used for the DH operations. If B<method> is B<NULL>, -the default method is used. +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 dependant 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 @@ -77,13 +89,24 @@ B<DH_METHOD>s. DH_set_default_method() returns no value. -DH_set_method() returns a pointer to the B<DH_METHOD> previously -associated with B<dh>. +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 B<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 +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)> @@ -93,4 +116,14 @@ L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> 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/crypto/openssl/doc/crypto/DSA_SIG_new.pod b/crypto/openssl/doc/crypto/DSA_SIG_new.pod index 6716555..3ac6140 100644 --- a/crypto/openssl/doc/crypto/DSA_SIG_new.pod +++ b/crypto/openssl/doc/crypto/DSA_SIG_new.pod @@ -30,7 +30,8 @@ DSA_SIG_free() returns no value. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<DSA_do_sign(3)|DSA_do_sign(3)> +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 diff --git a/crypto/openssl/doc/crypto/DSA_do_sign.pod b/crypto/openssl/doc/crypto/DSA_do_sign.pod index a24fd57..5dfc733 100644 --- a/crypto/openssl/doc/crypto/DSA_do_sign.pod +++ b/crypto/openssl/doc/crypto/DSA_do_sign.pod @@ -36,7 +36,7 @@ L<ERR_get_error(3)|ERR_get_error(3)>. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, +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)> diff --git a/crypto/openssl/doc/crypto/DSA_dup_DH.pod b/crypto/openssl/doc/crypto/DSA_dup_DH.pod index 29cb107..7f6f0d1 100644 --- a/crypto/openssl/doc/crypto/DSA_dup_DH.pod +++ b/crypto/openssl/doc/crypto/DSA_dup_DH.pod @@ -8,7 +8,7 @@ DSA_dup_DH - create a DH structure out of DSA structure #include <openssl/dsa.h> - DH * DSA_dup_DH(DSA *r); + DH * DSA_dup_DH(const DSA *r); =head1 DESCRIPTION @@ -27,7 +27,7 @@ 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(3)|err(3)> +L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/DSA_generate_key.pod b/crypto/openssl/doc/crypto/DSA_generate_key.pod index 52890db..af83ccf 100644 --- a/crypto/openssl/doc/crypto/DSA_generate_key.pod +++ b/crypto/openssl/doc/crypto/DSA_generate_key.pod @@ -24,7 +24,8 @@ 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(3)|err(3)>, L<rand(3)|rand(3)>, L<DSA_generate_parameters(3)|DSA_generate_parameters(3)> +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 diff --git a/crypto/openssl/doc/crypto/DSA_generate_parameters.pod b/crypto/openssl/doc/crypto/DSA_generate_parameters.pod index 43f60b0..be7c924 100644 --- a/crypto/openssl/doc/crypto/DSA_generate_parameters.pod +++ b/crypto/openssl/doc/crypto/DSA_generate_parameters.pod @@ -90,7 +90,7 @@ Seed lengths E<gt> 20 are not supported. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, +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)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/DSA_new.pod b/crypto/openssl/doc/crypto/DSA_new.pod index 7dde544..48e9b82 100644 --- a/crypto/openssl/doc/crypto/DSA_new.pod +++ b/crypto/openssl/doc/crypto/DSA_new.pod @@ -14,7 +14,8 @@ DSA_new, DSA_free - allocate and free DSA objects =head1 DESCRIPTION -DSA_new() allocates and initializes a B<DSA> structure. +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. @@ -30,7 +31,7 @@ DSA_free() returns no value. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, +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)> diff --git a/crypto/openssl/doc/crypto/DSA_set_method.pod b/crypto/openssl/doc/crypto/DSA_set_method.pod index cabc3c0..bc3cfb1 100644 --- a/crypto/openssl/doc/crypto/DSA_set_method.pod +++ b/crypto/openssl/doc/crypto/DSA_set_method.pod @@ -2,20 +2,21 @@ =head1 NAME -DSA_set_default_method, DSA_get_default_method, DSA_set_method, -DSA_new_method, DSA_OpenSSL - select DSA method +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(DSA_METHOD *meth); + void DSA_set_default_method(const DSA_METHOD *meth); - DSA_METHOD *DSA_get_default_method(void); + const DSA_METHOD *DSA_get_default_method(void); - DSA_METHOD *DSA_set_method(DSA *dsa, DSA_METHOD *meth); + int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); - DSA *DSA_new_method(DSA_METHOD *meth); + DSA *DSA_new_method(ENGINE *engine); DSA_METHOD *DSA_OpenSSL(void); @@ -23,22 +24,35 @@ DSA_new_method, DSA_OpenSSL - select DSA method 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. +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 is to use the OpenSSL internal implementation. -DSA_OpenSSL() returns a pointer to that method. +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 B<DSA> -structures created later. +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 -method. - -DSA_set_method() selects B<meth> for all operations using the structure B<dsa>. - -DSA_new_method() allocates and initializes a B<DSA> structure so that -B<method> will be used for the DSA operations. If B<method> is B<NULL>, -the default method is used. +DSA_METHOD. However, the meaningfulness of this result is dependant 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 @@ -84,18 +98,28 @@ struct =head1 RETURN VALUES -DSA_OpenSSL() and DSA_get_default_method() return pointers to the -respective B<DSA_METHOD>s. +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 a pointer to the B<DSA_METHOD> previously -associated with B<dsa>. +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 B<NULL> and sets an error code that can be +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. +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 @@ -106,4 +130,14 @@ L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)> 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/crypto/openssl/doc/crypto/DSA_sign.pod b/crypto/openssl/doc/crypto/DSA_sign.pod index f6e60a8..97389e8 100644 --- a/crypto/openssl/doc/crypto/DSA_sign.pod +++ b/crypto/openssl/doc/crypto/DSA_sign.pod @@ -55,7 +55,7 @@ Standard, DSS), ANSI X9.30 =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, +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 diff --git a/crypto/openssl/doc/crypto/DSA_size.pod b/crypto/openssl/doc/crypto/DSA_size.pod index 23b6320..ba4f650 100644 --- a/crypto/openssl/doc/crypto/DSA_size.pod +++ b/crypto/openssl/doc/crypto/DSA_size.pod @@ -8,7 +8,7 @@ DSA_size - get DSA signature size #include <openssl/dsa.h> - int DSA_size(DSA *dsa); + int DSA_size(const DSA *dsa); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/crypto/ERR_get_error.pod b/crypto/openssl/doc/crypto/ERR_get_error.pod index 3551bac..3444304 100644 --- a/crypto/openssl/doc/crypto/ERR_get_error.pod +++ b/crypto/openssl/doc/crypto/ERR_get_error.pod @@ -2,8 +2,10 @@ =head1 NAME -ERR_get_error, ERR_peek_error, ERR_get_error_line, ERR_peek_error_line, -ERR_get_error_line_data, ERR_peek_error_line_data - obtain error code and data +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 @@ -11,22 +13,29 @@ ERR_get_error_line_data, ERR_peek_error_line_data - obtain error code and data 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 last error code from the thread's error +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 last error code from the thread's +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 @@ -34,12 +43,14 @@ 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() and ERR_peek_error_line() are the same as the -above, but they additionally store the file name and line number where +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() and ERR_peek_error_line_data() store -additional data and flags associated with the error code in *B<data> +ERR_get_error_line_data(), ERR_peek_error_line_data() and +ERR_get_last_error_line_data() store additional data and flags +associated with the error code in *B<data> and *B<flags>, unless these are B<NULL>. *B<data> contains a string if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by OPENSSL_malloc(), *B<flags>&B<ERR_TXT_MALLOCED> is true. @@ -59,5 +70,7 @@ 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/crypto/openssl/doc/crypto/EVP_BytesToKey.pod b/crypto/openssl/doc/crypto/EVP_BytesToKey.pod new file mode 100644 index 0000000..5ce4add --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_BytesToKey.pod @@ -0,0 +1,67 @@ +=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> paramter 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 more standard algorithms such as PKCS#5 +v2.0 for key derivation. + +=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 + +EVP_BytesToKey() returns the size of the derived key in bytes. + +=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/crypto/openssl/doc/crypto/EVP_DigestInit.pod b/crypto/openssl/doc/crypto/EVP_DigestInit.pod index b99ecd2..5901c39 100644 --- a/crypto/openssl/doc/crypto/EVP_DigestInit.pod +++ b/crypto/openssl/doc/crypto/EVP_DigestInit.pod @@ -2,9 +2,10 @@ =head1 NAME -EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal, EVP_MAX_MD_SIZE, -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_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_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_dss, EVP_dss1, EVP_mdc2, EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines @@ -13,15 +14,28 @@ EVP digest routines #include <openssl/evp.h> - void EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); - void EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); - void EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, + 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, unsigned int cnt); + int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); - #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ + 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 (16+20) /* The SSLv3 md5+sha1 type */ + + #define EVP_MD_type(e) ((e)->type) #define EVP_MD_pkey_type(e) ((e)->pkey_type) #define EVP_MD_size(e) ((e)->md_size) @@ -32,15 +46,15 @@ EVP digest routines #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) - EVP_MD *EVP_md_null(void); - EVP_MD *EVP_md2(void); - EVP_MD *EVP_md5(void); - EVP_MD *EVP_sha(void); - EVP_MD *EVP_sha1(void); - EVP_MD *EVP_dss(void); - EVP_MD *EVP_dss1(void); - EVP_MD *EVP_mdc2(void); - EVP_MD *EVP_ripemd160(void); + 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_get_digestbyname(const char *name); #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) @@ -50,25 +64,48 @@ EVP digest routines The EVP digest routines are a high level interface to message digests. -EVP_DigestInit() initializes a digest context B<ctx> to use a digest -B<type>: this will typically be supplied by a function such as -EVP_sha1(). +EVP_MD_CTX_init() initializes digest contet B<ctx>. + +EVP_MD_CTX_create() allocates, initializes and returns a digest contet. + +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() retrieves the digest value from B<ctx> and places +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() no additional calls to EVP_DigestUpdate() -can be made, but EVP_DigestInit() can be called to initialize a new +After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() +can be made, but EVP_DigestInit_ex() can be called to initialize a new digest operation. -EVP_MD_CTX_copy() can be used to copy the message digest state from +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. +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 +contet 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 @@ -107,9 +144,10 @@ using, for example, OpenSSL_add_all_digests() for these functions to work. =head1 RETURN VALUES -EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() do not return values. +EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for +success and 0 for failure. -EVP_MD_CTX_copy() returns 1 if successful or 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. @@ -134,6 +172,19 @@ transparent to the digest used and much more flexible. SHA1 is the digest of choice for new applications. 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. + =head1 EXAMPLE This example digests the data "Test Message\n" and "Hello World\n", using the @@ -165,10 +216,12 @@ digest name passed on the command line. exit(1); } - EVP_DigestInit(&mdctx, md); + EVP_MD_CTX_init(&mdctx); + EVP_DigestInit_ex(&mdctx, md, NULL); EVP_DigestUpdate(&mdctx, mess1, strlen(mess1)); EVP_DigestUpdate(&mdctx, mess2, strlen(mess2)); - EVP_DigestFinal(&mdctx, md_value, &md_len); + EVP_DigestFinal_ex(&mdctx, md_value, &md_len); + EVP_MD_CTX_cleanup(&mdctx); printf("Digest is: "); for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); @@ -177,17 +230,10 @@ digest name passed on the command line. =head1 BUGS -Several of the functions do not return values: maybe they should. Although the -internal digest operations will never fail some future hardware based operations -might. - The link between digests and signing algorithms results in a situation where EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS even though they are identical digests. -The size of an B<EVP_MD_CTX> structure is determined at compile time: this results -in code that must be recompiled if the size of B<EVP_MD_CTX> increases. - =head1 SEE ALSO L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, @@ -199,4 +245,12 @@ L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> 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 truely const EVP_MD * in OpenSSL 0.9.7. + =cut diff --git a/crypto/openssl/doc/crypto/EVP_EncryptInit.pod b/crypto/openssl/doc/crypto/EVP_EncryptInit.pod index 483ff62..daf57e5 100644 --- a/crypto/openssl/doc/crypto/EVP_EncryptInit.pod +++ b/crypto/openssl/doc/crypto/EVP_EncryptInit.pod @@ -2,43 +2,65 @@ =head1 NAME -EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal, EVP_DecryptInit, -EVP_DecryptUpdate, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherUpdate, -EVP_CipherFinal, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, -EVP_CIPHER_CTX_cleanup, 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 routines +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 cipher routines =head1 SYNOPSIS #include <openssl/evp.h> - int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv); + int 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_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); 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_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); 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); @@ -74,14 +96,19 @@ EVP_CIPHER_asn1_to_param - EVP cipher routines The EVP cipher routines are a high level interface to certain symmetric ciphers. -EVP_EncryptInit() initializes a cipher context B<ctx> for encryption -with cipher B<type>. B<type> is normally supplied by a function such -as EVP_des_cbc() . 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_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_des_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 @@ -89,32 +116,49 @@ multiple times to encrypt successive blocks of data. The amount of data written depends on the block alignment of the encrypted data: as a result the amount of data written may be anything from zero bytes to (inl + cipher_block_size - 1) so B<outl> should contain sufficient -room. The actual number of bytes written is placed in B<outl>. +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. -EVP_EncryptFinal() 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(), EVP_DecryptUpdate() and EVP_DecryptFinal() are the +EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the corresponding decryption operations. EVP_DecryptFinal() will return an -error code if the final block is not correctly formatted. The parameters -and restrictions are identical to the encryption operations except that -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(), EVP_CipherUpdate() and EVP_CipherFinal() 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. -It should be called after all operations using a cipher are complete -so sensitive information does not remain in memory. +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> paramter does not need to be +initialized and they always use the default cipher implementation. + +EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a +similar way to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and +EVP_CipherFinal_ex() except B<ctx> is automatically cleaned up +after the call. EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() return an EVP_CIPHER structure when passed a cipher name, a NID or an @@ -125,6 +169,13 @@ 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 @@ -185,14 +236,14 @@ RC5 can be set. =head1 RETURN VALUES -EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() return 1 for success -and 0 for failure. +EVP_CIPHER_CTX_init, EVP_EncryptInit_ex(), EVP_EncryptUpdate() and +EVP_EncryptFinal_ex() return 1 for success and 0 for failure. -EVP_DecryptInit() and EVP_DecryptUpdate() return 1 for success and 0 for failure. -EVP_DecryptFinal() returns 0 if the decrypt failed or 1 for success. +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() and EVP_CipherUpdate() return 1 for success and 0 for failure. -EVP_CipherFinal() returns 0 for a decryption failure 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. @@ -207,6 +258,8 @@ 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. @@ -301,25 +354,26 @@ 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, 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. +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_EncryptUpdate(), EVP_EncryptFinal(), -EVP_DecryptInit(), EVP_DecryptUpdate(), EVP_CipherInit() and EVP_CipherUpdate() -and EVP_CIPHER_CTX_cleanup() did not return errors in OpenSSL version 0.9.5a or -earlier. Software only versions of encryption algorithms will never return -error codes for these functions, unless there is a programming error (for example -and attempt to set the key before the cipher is set in EVP_EncryptInit() ). +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. -It should be possible to disable PKCS padding: currently it isn't. - 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 @@ -333,22 +387,113 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. Get the number of rounds used in RC5: int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &i); + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); Get the RC2 effective key length: int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &i); + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); Set the number of rounds used in RC5: int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, i, NULL); + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); -Set the number of rounds used in RC2: +Set the effective key length used in RC2: + + int key_bits; + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); + +Encrypt a string using blowfish: + + 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_bf_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: + + S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d> + +General encryption, decryption function example using FILE I/O and RC2 with an +80 bit key: + + int do_crypt(FILE *in, FILE *out, int do_encrypt) + { + /* Allow enough space in output buffer for additional block */ + inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; + int inlen, outlen; + /* Bogus key and IV: we'd normally set these from + * another source. + */ + unsigned char key[] = "0123456789"; + unsigned char iv[] = "12345678"; + /* Don't set key or IV because we will modify the parameters */ + EVP_CIPHER_CTX_init(&ctx); + EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt); + EVP_CIPHER_CTX_set_key_length(&ctx, 10); + /* We finished modifying parameters so now we can set key and IV */ + EVP_CipherInit_ex(&ctx, 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 */ + return 0; + } + fwrite(outbuf, 1, outlen, out); + } + if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) + { + /* Error */ + return 0; + } + fwrite(outbuf, 1, outlen, out); + + EVP_CIPHER_CTX_cleanup(&ctx); + return 1; + } - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, i, NULL); =head1 SEE ALSO @@ -356,4 +501,9 @@ 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. + =cut diff --git a/crypto/openssl/doc/crypto/EVP_PKEY_new.pod b/crypto/openssl/doc/crypto/EVP_PKEY_new.pod new file mode 100644 index 0000000..10687e4 --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_PKEY_new.pod @@ -0,0 +1,47 @@ +=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/crypto/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod b/crypto/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod new file mode 100644 index 0000000..2db692e --- /dev/null +++ b/crypto/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod @@ -0,0 +1,80 @@ +=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() +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/crypto/openssl/doc/crypto/EVP_SealInit.pod b/crypto/openssl/doc/crypto/EVP_SealInit.pod index 0451eb6..25ef07f 100644 --- a/crypto/openssl/doc/crypto/EVP_SealInit.pod +++ b/crypto/openssl/doc/crypto/EVP_SealInit.pod @@ -73,4 +73,6 @@ 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/crypto/openssl/doc/crypto/EVP_SignInit.pod b/crypto/openssl/doc/crypto/EVP_SignInit.pod index 51d05ff..b203c3a 100644 --- a/crypto/openssl/doc/crypto/EVP_SignInit.pod +++ b/crypto/openssl/doc/crypto/EVP_SignInit.pod @@ -8,10 +8,12 @@ EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions #include <openssl/evp.h> - void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); - void EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + 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 @@ -19,9 +21,9 @@ EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions The EVP signature routines are a high level interface to digital signatures. -EVP_SignInit() initializes a signing context B<ctx> to using digest -B<type>: this will typically be supplied by a function such as -EVP_sha1(). +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 @@ -31,18 +33,18 @@ EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and places the signature in B<sig>. If the B<s> parameter is not NULL then 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. After calling EVP_SignFinal() no additional calls to -EVP_SignUpdate() can be made, but EVP_SignInit() can be called to initialize -a new signature operation. +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() and EVP_SignUpdate() do not return values. - -EVP_SignFinal() returns 1 for success and 0 for failure. +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. @@ -63,11 +65,18 @@ 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 -Several of the functions do not return values: maybe they should. Although the -internal digest operations will never fail some future hardware based operations -might. +Older versions of this documentation wrongly stated that calls to +EVP_SignUpdate() could not be made after calling EVP_SignFinal(). =head1 SEE ALSO @@ -82,4 +91,6 @@ L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> 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/crypto/openssl/doc/crypto/EVP_VerifyInit.pod b/crypto/openssl/doc/crypto/EVP_VerifyInit.pod index 5d0d1fb..b6afaed 100644 --- a/crypto/openssl/doc/crypto/EVP_VerifyInit.pod +++ b/crypto/openssl/doc/crypto/EVP_VerifyInit.pod @@ -8,30 +8,35 @@ EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification f #include <openssl/evp.h> - void EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); - void EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + 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() initializes a verification context B<ctx> to using digest -B<type>: this will typically be supplied by a function such as EVP_sha1(). +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>. After calling EVP_VerifyFinal() -no additional calls to EVP_VerifyUpdate() can be made, but EVP_VerifyInit() -can be called to initialize a new verification operation. +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() and EVP_VerifyUpdate() do not 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. @@ -49,11 +54,18 @@ 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 -Several of the functions do not return values: maybe they should. Although the -internal digest operations will never fail some future hardware based operations -might. +Older versions of this documentation wrongly stated that calls to +EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal(). =head1 SEE ALSO @@ -69,4 +81,6 @@ L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> 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/crypto/openssl/doc/crypto/OBJ_nid2obj.pod b/crypto/openssl/doc/crypto/OBJ_nid2obj.pod new file mode 100644 index 0000000..7dcc079 --- /dev/null +++ b/crypto/openssl/doc/crypto/OBJ_nid2obj.pod @@ -0,0 +1,149 @@ +=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 + + 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. + +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. + +=head1 EXAMPLES + +Create an object for B<commonName>: + + ASN1_OBJECT *o; + o = OBJ_nid2obj(NID_commonName); + +Check if an object is B<commonName> + + if (OBJ_obj2nid(obj) == NID_commonName) + /* Do something */ + +Create a new NID and initialize an object from it: + + int new_nid; + ASN1_OBJECT *obj; + new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); + + obj = OBJ_nid2obj(new_nid); + +Create a new object directly: + + obj = OBJ_txt2obj("1.2.3.4", 1); + +=head1 BUGS + +OBJ_obj2txt() is awkward and messy to use: it doesn't follow the +convention of other OpenSSL functions where the buffer can be set +to B<NULL> to determine the amount of data that should be written. +Instead B<buf> must point to a valid buffer and B<buf_len> should +be set to a positive value. A buffer length of 80 should be more +than enough to handle any OID encountered in practice. + +=head1 RETURN VALUES + +OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an +error occurred. + +OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> +on error. + +OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return +a NID or B<NID_undef> on error. + +=head1 SEE ALSO + +L<ERR_get_error(3)|ERR_get_error(3)> + +=head1 HISTORY + +TBA + +=cut diff --git a/crypto/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/crypto/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod index e8beac2..c39ac35 100644 --- a/crypto/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod +++ b/crypto/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod @@ -75,6 +75,11 @@ or "built on: date not available" otherwise. 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. @@ -91,5 +96,6 @@ L<crypto(3)|crypto(3)> 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/crypto/openssl/doc/crypto/PKCS12_create.pod b/crypto/openssl/doc/crypto/PKCS12_create.pod new file mode 100644 index 0000000..48f3bb8 --- /dev/null +++ b/crypto/openssl/doc/crypto/PKCS12_create.pod @@ -0,0 +1,57 @@ +=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 SEE ALSO + +L<d2i_PKCS12(3)|d2i_PKCS12(3)> + +=head1 HISTORY + +PKCS12_create was added in OpenSSL 0.9.3 + +=cut diff --git a/crypto/openssl/doc/crypto/PKCS12_parse.pod b/crypto/openssl/doc/crypto/PKCS12_parse.pod new file mode 100644 index 0000000..51344f8 --- /dev/null +++ b/crypto/openssl/doc/crypto/PKCS12_parse.pod @@ -0,0 +1,50 @@ +=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 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 store 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/crypto/openssl/doc/crypto/PKCS7_decrypt.pod b/crypto/openssl/doc/crypto/PKCS7_decrypt.pod new file mode 100644 index 0000000..b0ca067 --- /dev/null +++ b/crypto/openssl/doc/crypto/PKCS7_decrypt.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure + +=head1 SYNOPSIS + +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/crypto/openssl/doc/crypto/PKCS7_encrypt.pod b/crypto/openssl/doc/crypto/PKCS7_encrypt.pod new file mode 100644 index 0000000..1a507b2 --- /dev/null +++ b/crypto/openssl/doc/crypto/PKCS7_encrypt.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +PKCS7_encrypt - create a PKCS#7 envelopedData structure + +=head1 SYNOPSIS + +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. + +=head1 RETURN VALUES + +PKCS7_encrypt() returns either a valid PKCS7 structure or NULL if an error occurred. +The error can be obtained from ERR_get_error(3). + +=head1 BUGS + +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_decrypt(3)|PKCS7_decrypt(3)> + +=head1 HISTORY + +PKCS7_decrypt() was added to OpenSSL 0.9.5 + +=cut diff --git a/crypto/openssl/doc/crypto/PKCS7_sign.pod b/crypto/openssl/doc/crypto/PKCS7_sign.pod new file mode 100644 index 0000000..fc7e649 --- /dev/null +++ b/crypto/openssl/doc/crypto/PKCS7_sign.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +PKCS7_sign - create a PKCS#7 signedData structure + +=head1 SYNOPSIS + +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. + +=head1 BUGS + +PKCS7_sign() is somewhat limited. It does not support multiple signers, some +advanced attributes such as counter signatures are not supported. + +The SHA1 digest algorithm is currently always used. + +When the signed data is not detached it will be stored in memory within the +B<PKCS7> structure. This effectively limits the size of messages which can be +signed due to memory restraints. There should be a way to sign data without +having to hold it all in memory, this would however require fairly major +revisions of the OpenSSL ASN1 code. + +Clear text signing does not store the content in memory but the way PKCS7_sign() +operates means that two passes of the data must typically be made: one to compute +the signatures and a second to output the data along with the signature. There +should be a way to process the data with only a single pass. + +=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 + +=cut diff --git a/crypto/openssl/doc/crypto/PKCS7_verify.pod b/crypto/openssl/doc/crypto/PKCS7_verify.pod new file mode 100644 index 0000000..07c9fda --- /dev/null +++ b/crypto/openssl/doc/crypto/PKCS7_verify.pod @@ -0,0 +1,116 @@ +=pod + +=head1 NAME + +PKCS7_verify - verify a PKCS#7 signedData structure + +=head1 SYNOPSIS + +int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags); + +int 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 1 for a successful verification and zero or a negative +value 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/crypto/openssl/doc/crypto/RAND_bytes.pod b/crypto/openssl/doc/crypto/RAND_bytes.pod index b6ebd50..ce6329c 100644 --- a/crypto/openssl/doc/crypto/RAND_bytes.pod +++ b/crypto/openssl/doc/crypto/RAND_bytes.pod @@ -35,7 +35,8 @@ method. =head1 SEE ALSO -L<rand(3)|rand(3)>, L<err(3)|err(3)>, L<RAND_add(3)|RAND_add(3)> +L<rand(3)|rand(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, +L<RAND_add(3)|RAND_add(3)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/RAND_egd.pod b/crypto/openssl/doc/crypto/RAND_egd.pod index 71cab3c..62adbe1 100644 --- a/crypto/openssl/doc/crypto/RAND_egd.pod +++ b/crypto/openssl/doc/crypto/RAND_egd.pod @@ -11,6 +11,8 @@ RAND_egd - query entropy gathering daemon 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>. @@ -27,6 +29,11 @@ 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, @@ -47,12 +54,19 @@ http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html . 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)>, @@ -64,4 +78,8 @@ 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/crypto/openssl/doc/crypto/RAND_set_rand_method.pod b/crypto/openssl/doc/crypto/RAND_set_rand_method.pod index 464eba4..c9bb6d9 100644 --- a/crypto/openssl/doc/crypto/RAND_set_rand_method.pod +++ b/crypto/openssl/doc/crypto/RAND_set_rand_method.pod @@ -8,22 +8,30 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method #include <openssl/rand.h> - void RAND_set_rand_method(RAND_METHOD *meth); + void RAND_set_rand_method(const RAND_METHOD *meth); - RAND_METHOD *RAND_get_rand_method(void); + 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. Initially, the -default is to use the OpenSSL internal implementation. RAND_SSLeay() -returns a pointer to that method. +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. -RAND_set_rand_method() sets the RAND method to B<meth>. -RAND_get_rand_method() returns a pointer to the current method. +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 dependant on whether the ENGINE +API is being used, so this function is no longer recommended. =head1 THE RAND_METHOD STRUCTURE @@ -47,13 +55,29 @@ Each component may be NULL if the function is not implemented. 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<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/crypto/openssl/doc/crypto/RSA_check_key.pod b/crypto/openssl/doc/crypto/RSA_check_key.pod index 8a42d2e..a5198f3 100644 --- a/crypto/openssl/doc/crypto/RSA_check_key.pod +++ b/crypto/openssl/doc/crypto/RSA_check_key.pod @@ -37,12 +37,31 @@ 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(3)|err(3)> +L<rsa(3)|rsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> =head1 HISTORY -RSA_check() appeared in OpenSSL 0.9.4. +RSA_check_key() appeared in OpenSSL 0.9.4. =cut diff --git a/crypto/openssl/doc/crypto/RSA_generate_key.pod b/crypto/openssl/doc/crypto/RSA_generate_key.pod index 8714f71..52dbb14 100644 --- a/crypto/openssl/doc/crypto/RSA_generate_key.pod +++ b/crypto/openssl/doc/crypto/RSA_generate_key.pod @@ -59,7 +59,8 @@ RSA_generate_key() goes into an infinite loop for illegal input values. =head1 SEE ALSO -L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_free(3)|RSA_free(3)> +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)> =head1 HISTORY diff --git a/crypto/openssl/doc/crypto/RSA_new.pod b/crypto/openssl/doc/crypto/RSA_new.pod index f16490e..3d15b92 100644 --- a/crypto/openssl/doc/crypto/RSA_new.pod +++ b/crypto/openssl/doc/crypto/RSA_new.pod @@ -14,7 +14,8 @@ RSA_new, RSA_free - allocate and free RSA objects =head1 DESCRIPTION -RSA_new() allocates and initializes an B<RSA> structure. +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. @@ -29,7 +30,9 @@ RSA_free() returns no value. =head1 SEE ALSO -L<err(3)|err(3)>, L<rsa(3)|rsa(3)>, L<RSA_generate_key(3)|RSA_generate_key(3)> +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 diff --git a/crypto/openssl/doc/crypto/RSA_print.pod b/crypto/openssl/doc/crypto/RSA_print.pod index 67876fa..e28d107 100644 --- a/crypto/openssl/doc/crypto/RSA_print.pod +++ b/crypto/openssl/doc/crypto/RSA_print.pod @@ -2,9 +2,9 @@ =head1 NAME -RSA_print, RSA_print_fp, DHparams_print, DHparams_print_fp, DSA_print, -DSA_print_fp, DHparams_print, DHparams_print_fp - print cryptographic -parameters +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 diff --git a/crypto/openssl/doc/crypto/RSA_private_encrypt.pod b/crypto/openssl/doc/crypto/RSA_private_encrypt.pod index 6861a98..746a80c 100644 --- a/crypto/openssl/doc/crypto/RSA_private_encrypt.pod +++ b/crypto/openssl/doc/crypto/RSA_private_encrypt.pod @@ -59,7 +59,8 @@ obtained by L<ERR_get_error(3)|ERR_get_error(3)>. =head1 SEE ALSO -L<err(3)|err(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> +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 diff --git a/crypto/openssl/doc/crypto/RSA_public_encrypt.pod b/crypto/openssl/doc/crypto/RSA_public_encrypt.pod index 02edb7a..d53e19d 100644 --- a/crypto/openssl/doc/crypto/RSA_public_encrypt.pod +++ b/crypto/openssl/doc/crypto/RSA_public_encrypt.pod @@ -72,11 +72,8 @@ SSL, PKCS #1 v2.0 =head1 SEE ALSO -L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_size(3)|RSA_size(3)> - -=head1 NOTES - -The L<RSA_PKCS1_RSAref(3)|RSA_PKCS1_RSAref(3)> method supports only the RSA_PKCS1_PADDING mode. +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 diff --git a/crypto/openssl/doc/crypto/RSA_set_method.pod b/crypto/openssl/doc/crypto/RSA_set_method.pod index c1a5b39..0a305f6 100644 --- a/crypto/openssl/doc/crypto/RSA_set_method.pod +++ b/crypto/openssl/doc/crypto/RSA_set_method.pod @@ -3,60 +3,71 @@ =head1 NAME RSA_set_default_method, RSA_get_default_method, RSA_set_method, -RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref, -RSA_null_method, RSA_flags, RSA_new_method - select RSA 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(RSA_METHOD *meth); + void RSA_set_default_method(const RSA_METHOD *meth); RSA_METHOD *RSA_get_default_method(void); - RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth); + int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); - RSA_METHOD *RSA_get_method(RSA *rsa); + RSA_METHOD *RSA_get_method(const RSA *rsa); RSA_METHOD *RSA_PKCS1_SSLeay(void); - RSA_METHOD *RSA_PKCS1_RSAref(void); - RSA_METHOD *RSA_null_method(void); - int RSA_flags(RSA *rsa); + 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. - -Initially, the default is to use the OpenSSL internal implementation, -unless OpenSSL was configured with the C<rsaref> or C<-DRSA_NULL> -options. RSA_PKCS1_SSLeay() returns a pointer to that method. +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. -RSA_PKCS1_RSAref() returns a pointer to a method that uses the RSAref -library. This is the default method in the C<rsaref> configuration; -the function is not available in other configurations. -RSA_null_method() returns a pointer to a method that does not support -the RSA transformation. It is the default if OpenSSL is compiled with -C<-DRSA_NULL>. These methods may be useful in the USA because of a -patent on the RSA cryptosystem. +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 B<RSA> -structures created later. +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 -method. - -RSA_set_method() selects B<meth> for all operations using the key -B<rsa>. - -RSA_get_method() returns a pointer to the method currently selected -for B<rsa>. +RSA_METHOD. However, the meaningfulness of this result is dependant 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. @@ -127,18 +138,44 @@ the default method is used. =head1 RETURN VALUES -RSA_PKCS1_SSLeay(), RSA_PKCS1_RSAref(), RSA_PKCS1_null_method(), -RSA_get_default_method() and RSA_get_method() return pointers to the -respective B<RSA_METHOD>s. +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 B<RSA_METHOD> previously -associated with B<rsa>. - -RSA_new_method() returns B<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. +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 @@ -151,4 +188,15 @@ 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/crypto/openssl/doc/crypto/RSA_sign.pod b/crypto/openssl/doc/crypto/RSA_sign.pod index f0bf6ee..71688a6 100644 --- a/crypto/openssl/doc/crypto/RSA_sign.pod +++ b/crypto/openssl/doc/crypto/RSA_sign.pod @@ -50,8 +50,8 @@ SSL, PKCS #1 v2.0 =head1 SEE ALSO -L<err(3)|err(3)>, L<objects(3)|objects(3)>, L<rsa(3)|rsa(3)>, -L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, +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 diff --git a/crypto/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/crypto/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod index df9ceb3..e70380b 100644 --- a/crypto/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod +++ b/crypto/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod @@ -47,8 +47,8 @@ These functions serve no recognizable purpose. =head1 SEE ALSO -L<err(3)|err(3)>, L<objects(3)|objects(3)>, L<rand(3)|rand(3)>, -L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, +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 diff --git a/crypto/openssl/doc/crypto/RSA_size.pod b/crypto/openssl/doc/crypto/RSA_size.pod index b36b4d5..5b7f835 100644 --- a/crypto/openssl/doc/crypto/RSA_size.pod +++ b/crypto/openssl/doc/crypto/RSA_size.pod @@ -8,7 +8,7 @@ RSA_size - get RSA modulus size #include <openssl/rsa.h> - int RSA_size(RSA *rsa); + int RSA_size(const RSA *rsa); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/crypto/SMIME_read_PKCS7.pod b/crypto/openssl/doc/crypto/SMIME_read_PKCS7.pod new file mode 100644 index 0000000..ffafa37 --- /dev/null +++ b/crypto/openssl/doc/crypto/SMIME_read_PKCS7.pod @@ -0,0 +1,71 @@ +=pod + +=head1 NAME + +SMIME_read_PKCS7 - parse S/MIME message. + +=head1 SYNOPSIS + +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/crypto/openssl/doc/crypto/SMIME_write_PKCS7.pod b/crypto/openssl/doc/crypto/SMIME_write_PKCS7.pod new file mode 100644 index 0000000..2cfad2e --- /dev/null +++ b/crypto/openssl/doc/crypto/SMIME_write_PKCS7.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format. + +=head1 SYNOPSIS + +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 cleartext signing (B<multipart/signed>) is +being used then the signed data 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 cleartext signing is being used then the data must be read twice: +once to compute the signature in PKCS7_sign() and once to output the +S/MIME message. + +=head1 BUGS + +SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there +should be an option to disable this. + +There should really be a way to produce cleartext signing using only +a single pass of the data. + +=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/crypto/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod b/crypto/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod new file mode 100644 index 0000000..d287c18 --- /dev/null +++ b/crypto/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod @@ -0,0 +1,72 @@ +=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 + +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, unsigned char *bytes, int len); + +X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, char *field, int type, 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,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/crypto/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod b/crypto/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod new file mode 100644 index 0000000..4472a1c --- /dev/null +++ b/crypto/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod @@ -0,0 +1,110 @@ +=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 + +int X509_NAME_add_entry_by_txt(X509_NAME *name, char *field, int type, 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 recommened 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, MBSTRING_ASC, + "C", "UK", -1, -1, 0)) + /* Error */ + if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, + "O", "Disorganized Organization", -1, -1, 0)) + /* Error */ + if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, + "CN", "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/crypto/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod b/crypto/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod new file mode 100644 index 0000000..333323d --- /dev/null +++ b/crypto/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod @@ -0,0 +1,106 @@ +=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 + +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. + +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. + +=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 loc; + X509_NAME_ENTRY *e; + + loc = -1; + 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_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/crypto/openssl/doc/crypto/X509_NAME_print_ex.pod b/crypto/openssl/doc/crypto/X509_NAME_print_ex.pod new file mode 100644 index 0000000..907c04f --- /dev/null +++ b/crypto/openssl/doc/crypto/X509_NAME_print_ex.pod @@ -0,0 +1,105 @@ +=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>. At most B<size> +bytes will be written. If B<buf> is B<NULL> then a buffer is dynamically allocated +and returned, otherwise 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_STRFLAGS_ESC_MSB> should be unset: so for example +B<XN_FLAG_ONELINE & ~ASN1_STRFLAGS_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 it 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 is 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/crypto/openssl/doc/crypto/X509_new.pod b/crypto/openssl/doc/crypto/X509_new.pod new file mode 100644 index 0000000..fd5fc65 --- /dev/null +++ b/crypto/openssl/doc/crypto/X509_new.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +X509_new, X509_free - X509 certificate ASN1 allocation functions + +=head1 SYNOPSIS + + 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/crypto/openssl/doc/crypto/bn.pod b/crypto/openssl/doc/crypto/bn.pod index 1524bc2..210dfea 100644 --- a/crypto/openssl/doc/crypto/bn.pod +++ b/crypto/openssl/doc/crypto/bn.pod @@ -21,19 +21,27 @@ bn - multiprecision integer arithmetics 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); - int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b); + 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_sqr(BIGNUM *r, BIGNUM *a, 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); @@ -54,7 +62,7 @@ bn - multiprecision integer arithmetics int BN_zero(BIGNUM *a); int BN_one(BIGNUM *a); - BIGNUM *BN_value_one(void); + const BIGNUM *BN_value_one(void); int BN_set_word(BIGNUM *a, unsigned long w); unsigned long BN_get_word(BIGNUM *a); @@ -139,7 +147,7 @@ of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. 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_num_bytes(3)|BN_num_bytes(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)>, diff --git a/crypto/openssl/doc/crypto/bn_internal.pod b/crypto/openssl/doc/crypto/bn_internal.pod index 8da244a..9805a7c 100644 --- a/crypto/openssl/doc/crypto/bn_internal.pod +++ b/crypto/openssl/doc/crypto/bn_internal.pod @@ -34,9 +34,9 @@ library internal functions 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, - BN_ULONG *tmp); + int dna,int dnb,BN_ULONG *tmp); void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int tn, int n, BN_ULONG *tmp); + 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, @@ -152,14 +152,15 @@ 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<t>) operates on the B<n2> -word arrays B<a> and B<b> 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_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<tn>, B<n>, B<tmp>) operates -on the B<n>+B<tn> word arrays B<a> and B<b> and the 4*B<n> word arrays -B<r> and B<tmp>. +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> diff --git a/crypto/openssl/doc/crypto/crypto.pod b/crypto/openssl/doc/crypto/crypto.pod index c12eec1..7a52799 100644 --- a/crypto/openssl/doc/crypto/crypto.pod +++ b/crypto/openssl/doc/crypto/crypto.pod @@ -62,6 +62,22 @@ 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)> diff --git a/crypto/openssl/doc/crypto/d2i_ASN1_OBJECT.pod b/crypto/openssl/doc/crypto/d2i_ASN1_OBJECT.pod new file mode 100644 index 0000000..45bb184 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_ASN1_OBJECT.pod @@ -0,0 +1,29 @@ +=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/crypto/openssl/doc/crypto/d2i_DHparams.pod b/crypto/openssl/doc/crypto/d2i_DHparams.pod index a6d1743..1e98aeb 100644 --- a/crypto/openssl/doc/crypto/d2i_DHparams.pod +++ b/crypto/openssl/doc/crypto/d2i_DHparams.pod @@ -2,7 +2,7 @@ =head1 NAME -d2i_DHparams, i2d_DHparams - ... +d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions. =head1 SYNOPSIS @@ -13,18 +13,18 @@ d2i_DHparams, i2d_DHparams - ... =head1 DESCRIPTION -... +These functions decode and encode PKCS#3 DH parameters using the +DHparameter structure described in PKCS#3. -=head1 RETURN VALUES - -... +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/crypto/openssl/doc/crypto/d2i_DSAPublicKey.pod b/crypto/openssl/doc/crypto/d2i_DSAPublicKey.pod new file mode 100644 index 0000000..6ebd304 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_DSAPublicKey.pod @@ -0,0 +1,82 @@ +=pod + +=head1 NAME + +d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey, +d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding +and parsing functions. + +=head1 SYNOPSIS + + #include <openssl/dsa.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_PUKEY() and i2d_DSA_PUKEY() 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/crypto/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod b/crypto/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod new file mode 100644 index 0000000..a54b779 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod @@ -0,0 +1,56 @@ +=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/crypto/openssl/doc/crypto/d2i_RSAPublicKey.pod b/crypto/openssl/doc/crypto/d2i_RSAPublicKey.pod index ff4d0d5..7c71bcb 100644 --- a/crypto/openssl/doc/crypto/d2i_RSAPublicKey.pod +++ b/crypto/openssl/doc/crypto/d2i_RSAPublicKey.pod @@ -2,7 +2,9 @@ =head1 NAME -d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, i2d_Netscape_RSA, d2i_Netscape_RSA - ... +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 @@ -12,6 +14,10 @@ d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, i2d_Ne int i2d_RSAPublicKey(RSA *a, unsigned char **pp); + RSA * d2i_RSA_PUBKEY(RSA **a, unsigned char **pp, long length); + + int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp); + RSA * d2i_RSAPrivateKey(RSA **a, unsigned char **pp, long length); int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); @@ -22,18 +28,39 @@ d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, i2d_Ne =head1 DESCRIPTION -... +d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 RSAPublicKey +structure. + +d2i_RSA_PUKEY() and i2d_RSA_PUKEY() 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. -=head1 RETURN VALUES +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/crypto/openssl/doc/crypto/d2i_X509.pod b/crypto/openssl/doc/crypto/d2i_X509.pod new file mode 100644 index 0000000..5e3c3d0 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_X509.pod @@ -0,0 +1,231 @@ +=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, unsigned char **in, int len); + int i2d_X509(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(X509 *x, BIO *bp); + int i2d_X509_fp(X509 *x, FILE *fp); + +=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<*out>. 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. If the call is +successful B<*out> is incremented to the byte following the +parsed data. + +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. + +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. + +=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 that +B<i2d_X509> converts from internal to DER. + +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. + +=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)>. + +i2d_X509(), i2d_X509_bio() and i2d_X509_fp() return a 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() returns 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/crypto/openssl/doc/crypto/d2i_X509_ALGOR.pod b/crypto/openssl/doc/crypto/d2i_X509_ALGOR.pod new file mode 100644 index 0000000..9e5cd92 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_X509_ALGOR.pod @@ -0,0 +1,30 @@ +=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/crypto/openssl/doc/crypto/d2i_X509_CRL.pod b/crypto/openssl/doc/crypto/d2i_X509_CRL.pod new file mode 100644 index 0000000..06c5b23 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_X509_CRL.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_509_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, 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(X509_CRL *x, BIO *bp); + int i2d_X509_CRL_fp(X509_CRL *x, FILE *fp); + +=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/crypto/openssl/doc/crypto/d2i_X509_NAME.pod b/crypto/openssl/doc/crypto/d2i_X509_NAME.pod new file mode 100644 index 0000000..343ffe1 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_X509_NAME.pod @@ -0,0 +1,31 @@ +=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 +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/crypto/openssl/doc/crypto/d2i_X509_REQ.pod b/crypto/openssl/doc/crypto/d2i_X509_REQ.pod new file mode 100644 index 0000000..be4ad68 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_X509_REQ.pod @@ -0,0 +1,36 @@ +=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, 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(X509_REQ *x, BIO *bp); + int i2d_X509_REQ_fp(X509_REQ *x, FILE *fp); + +=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/crypto/openssl/doc/crypto/d2i_X509_SIG.pod b/crypto/openssl/doc/crypto/d2i_X509_SIG.pod new file mode 100644 index 0000000..e48fd79 --- /dev/null +++ b/crypto/openssl/doc/crypto/d2i_X509_SIG.pod @@ -0,0 +1,30 @@ +=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/crypto/openssl/doc/crypto/des.pod b/crypto/openssl/doc/crypto/des.pod index 9908039..528c73a 100644 --- a/crypto/openssl/doc/crypto/des.pod +++ b/crypto/openssl/doc/crypto/des.pod @@ -2,113 +2,105 @@ =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_read_password, des_read_2passwords, des_read_pw_string, -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 +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); + 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); + 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_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_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, + 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, + 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, + 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, + 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, + 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, + 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); - - 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); - - 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); - char *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); + 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 @@ -116,56 +108,52 @@ 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 +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)>; for backward -compatibility the function des_random_seed() is available as well). -If the PRNG could not generate a secure key, 0 is returned. In -earlier versions of the library, des_random_key() did not generate -secure keys. +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. +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 +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() (called des_key_sched() in the MIT library) 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 +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() (called des_fixup_key_parity() in the MIT -library) sets the parity of the passed I<key> to odd. +DES_set_odd_parity() sets the parity of the passed I<key> to odd. -des_is_weak_key() returns 1 is the passed key is a weak key, 0 if it +DES_is_weak_key() returns 1 is the passed key is a weak key, 0 if it is ok. The probability that a randomly generated key is weak is 1/2^52, so it is not really worth checking for them. The following routines mostly operate on an input and output stream of -I<des_cblock>s. +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> +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 +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. +and output may overlap. DES_ecb_encrypt() does not return a value. -des_ecb3_encrypt() encrypts/decrypts the I<input> block by using +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 @@ -173,10 +161,10 @@ 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 +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> +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> @@ -186,24 +174,24 @@ 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 +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 +DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with three keys. This means that each DES operation inside the CBC mode is really an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL. -The des_ede2_cbc_encrypt() macro implements two-key Triple-DES by +The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>. This form of Triple-DES is used by the RSAREF library. -des_pcbc_encrypt() encrypt/decrypts using the propagating cipher block +DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block chaining mode used by Kerberos v4. Its parameters are the same as -des_ncbc_encrypt(). +DES_ncbc_encrypt(). -des_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This +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 @@ -211,7 +199,7 @@ 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() +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 @@ -219,10 +207,10 @@ 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_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 +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 @@ -230,39 +218,22 @@ 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 +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. +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_read_pw_string() -is also available under the name EVP_read_pw_string(). - -des_read_pw_string() writes the string specified by I<prompt> to -standard output, turns echo off and reads in input string from the -terminal. The string is returned in I<buf>, which must have space for -at least I<length> bytes. If I<verify> is set, the user is asked for -the password twice and unless the two 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. - -des_read_password() does the same 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. 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(). - -des_cbc_cksum() produces an 8 byte checksum based on the input stream +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 +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 @@ -270,19 +241,19 @@ I<output>. The following are DES-based transformations: -des_fcrypt() is a fast version of the Unix crypt(3) function. This +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 +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 +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) @@ -290,40 +261,40 @@ 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 +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 +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() +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 +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 +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. +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)>. +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_3cbc_encrypt() is flawed and must not be used in applications. -des_cbc_encrypt() does not modify B<ivec>; use des_ncbc_encrypt() +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. +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 @@ -333,8 +304,9 @@ 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_read_pw_string() is the most machine/OS dependent function and -normally generates the most problems when porting this code. +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 @@ -349,10 +321,20 @@ 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(), des_read_password() and -des_string_to_key() are available in the MIT Kerberos library; +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. diff --git a/crypto/openssl/doc/crypto/dh.pod b/crypto/openssl/doc/crypto/dh.pod index 0a9b7c0..c3ccd06 100644 --- a/crypto/openssl/doc/crypto/dh.pod +++ b/crypto/openssl/doc/crypto/dh.pod @@ -7,24 +7,25 @@ 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(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(DH *dh, int *codes); + 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(DH_METHOD *meth); - DH_METHOD *DH_get_default_method(void); - DH_METHOD *DH_set_method(DH *dh, DH_METHOD *meth); - DH *DH_new_method(DH_METHOD *meth); - DH_METHOD *DH_OpenSSL(void); + 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)()); @@ -32,10 +33,10 @@ dh - Diffie-Hellman key agreement char *DH_get_ex_data(DH *d, int idx); DH * d2i_DHparams(DH **a, unsigned char **pp, long length); - int i2d_DHparams(DH *a, unsigned char **pp); + int i2d_DHparams(const DH *a, unsigned char **pp); - int DHparams_print_fp(FILE *fp, DH *x); - int DHparams_print(BIO *bp, DH *x); + int DHparams_print_fp(FILE *fp, const DH *x); + int DHparams_print(BIO *bp, const DH *x); =head1 DESCRIPTION @@ -56,11 +57,20 @@ The B<DH> structure consists of several BIGNUM components. }; 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<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<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)> diff --git a/crypto/openssl/doc/crypto/dsa.pod b/crypto/openssl/doc/crypto/dsa.pod index 2c09244..da07d2b 100644 --- a/crypto/openssl/doc/crypto/dsa.pod +++ b/crypto/openssl/doc/crypto/dsa.pod @@ -7,17 +7,18 @@ 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(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(DSA *r); + DH * DSA_dup_DH(const DSA *r); int DSA_generate_key(DSA *dsa); @@ -26,13 +27,13 @@ dsa - Digital Signature Algorithm int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, BIGNUM **rp); int DSA_verify(int dummy, const unsigned char *dgst, int len, - unsigned char *sigbuf, int siglen, DSA *dsa); + const unsigned char *sigbuf, int siglen, DSA *dsa); - void DSA_set_default_method(DSA_METHOD *meth); - DSA_METHOD *DSA_get_default_method(void); - DSA_METHOD *DSA_set_method(DSA *dsa, DSA_METHOD *meth); - DSA *DSA_new_method(DSA_METHOD *meth); - DSA_METHOD *DSA_OpenSSL(void); + 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)()); @@ -41,7 +42,7 @@ dsa - Digital Signature Algorithm DSA_SIG *DSA_SIG_new(void); void DSA_SIG_free(DSA_SIG *a); - int i2d_DSA_SIG(DSA_SIG *a, unsigned char **pp); + 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); @@ -51,14 +52,14 @@ dsa - Digital Signature Algorithm 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(DSA *a, unsigned char **pp); - int i2d_DSAPrivateKey(DSA *a, unsigned char **pp); - int i2d_DSAparams(DSA *a,unsigned char **pp); + 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, DSA *x); - int DSAparams_print_fp(FILE *fp, DSA *x); - int DSA_print(BIO *bp, DSA *x, int off); - int DSA_print_fp(FILE *bp, DSA *x, int off); + 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 @@ -84,6 +85,14 @@ The B<DSA> structure consists of several BIGNUM components. 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 @@ -92,7 +101,8 @@ 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<DSA_new(3)|DSA_new(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)>, diff --git a/crypto/openssl/doc/crypto/engine.pod b/crypto/openssl/doc/crypto/engine.pod new file mode 100644 index 0000000..c77dad5 --- /dev/null +++ b/crypto/openssl/doc/crypto/engine.pod @@ -0,0 +1,621 @@ +=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); + void ENGINE_load_cswift(void); + void ENGINE_load_chil(void); + void ENGINE_load_atalla(void); + void ENGINE_load_nuron(void); + void ENGINE_load_ubsec(void); + void ENGINE_load_aep(void); + void ENGINE_load_sureware(void); + void ENGINE_load_4758cca(void); + void ENGINE_load_openbsd_dev_crypto(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_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_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_DH(ENGINE *e); + void ENGINE_unregister_DH(ENGINE *e); + void ENGINE_register_all_DH(void); + int ENGINE_register_RAND(ENGINE *e); + void ENGINE_unregister_RAND(ENGINE *e); + void ENGINE_register_all_RAND(void); + int ENGINE_register_ciphers(ENGINE *e); + void ENGINE_unregister_ciphers(ENGINE *e); + void ENGINE_register_all_ciphers(void); + int ENGINE_register_digests(ENGINE *e); + void ENGINE_unregister_digests(ENGINE *e); + void ENGINE_register_all_digests(void); + int ENGINE_register_complete(ENGINE *e); + int ENGINE_register_all_complete(void); + + int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)()); + 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)(), 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_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_DH(ENGINE *e, const DH_METHOD *dh_meth); + int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); + int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); + int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); + int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); + int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); + int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); + int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); + int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); + int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); + int ENGINE_set_flags(ENGINE *e, int flags); + int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); + + const char *ENGINE_get_id(const ENGINE *e); + const char *ENGINE_get_name(const ENGINE *e); + const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); + const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); + const DH_METHOD *ENGINE_get_DH(const ENGINE *e); + const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); + ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); + ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); + ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); + ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); + ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); + ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); + ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); + ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); + const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); + const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); + int ENGINE_get_flags(const ENGINE *e); + const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); + + EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, + UI_METHOD *ui_method, void *callback_data); + EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, + UI_METHOD *ui_method, void *callback_data); + + 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 - alternative DSA, DH, and RAND + 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. you should obtain a new reference when +making copies of an ENGINE pointer if the copies will be used (and +released) independantly. + +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 - you need a structural reference +simply to refer to the pointer value at all, as this kind of reference is +your guarantee that the structure can not be deallocated until you release +your reference. + +However, a structural reference provides no guarantee that the ENGINE has +been initiliased to be usable to perform any of its cryptographic +implementations - and indeed it's quite possible that most ENGINEs will not +initialised at all on standard setups, 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 independantly. If you have a functional reference to an +ENGINE, you have a guarantee that the ENGINE has been initialised ready to +perform cryptographic operations and will not be uninitialised or cleaned +up until after you have released your reference. + +We will discuss the two kinds of reference separately, including how to +tell which one you are dealing with at any given point in time (after all +they are both simply (ENGINE *) pointers, the difference is in the way they +are used). + +I<Structural references> + +This basic type of reference is typically used for creating new ENGINEs +dynamically, 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. Other than that, structural references come from return +values to various ENGINE API functions 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. In this case, +the supplied ENGINE pointer is, from the point of the view of the caller, +both a structural reference and a functional reference - so if the caller +intends to use it as a functional reference it should free the structural +reference with ENGINE_free() first. If the caller wishes to use it only as +a structural reference (eg. if the ENGINE_init() call was simply to test if +the ENGINE seems available/online), then it should free the functional +reference; all functional references are released by the ENGINE_finish() +function. + +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 separated-out by an 'nid' index, because +abstractions like EVP_CIPHER and EVP_DIGEST support many distinct +algorithms and modes - ENGINEs will support different numbers and +combinations of these. 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. ENGINEs can be B<registered> into +these tables to make themselves available for use automatically by the +various abstractions, eg. RSA. For illustrative purposes, we continue with +the RSA example, though all comments apply similarly to the other +abstractions (they each get their own table and linkage to the +corresponding section of openssl code). + +When a new RSA key is being created, ie. in RSA_new_method(), a +"get_default" call will be made to the ENGINE subsystem to process the RSA +state table and return a functional reference to an initialised ENGINE +whose RSA_METHOD should be used. If no ENGINE should (or can) be used, it +will return NULL and the RSA key will operate with a NULL ENGINE handle by +using the conventional RSA implementation in OpenSSL (and will from then on +behave the way it used to before the ENGINE API existed - for details see +L<RSA_new_method(3)|RSA_new_method(3)>). + +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. + +It is worth illustrating the difference between "registration" of ENGINEs +into these per-algorithm state tables and using the alternative +"set_default" functions. The latter handles both "registration" and also +setting the cached "default" ENGINE in each relevant state table - so +registered ENGINEs will only have a chance to be initialised for use as a +default if a default ENGINE wasn't already set for the same state table. +Eg. if ENGINE X supports cipher nids {A,B} and RSA, ENGINE Y supports +ciphers {A} and DSA, and the following code is executed; + + ENGINE_register_complete(X); + ENGINE_set_default(Y, ENGINE_METHOD_ALL); + e1 = ENGINE_get_default_RSA(); + e2 = ENGINE_get_cipher_engine(A); + e3 = ENGINE_get_cipher_engine(B); + e4 = ENGINE_get_default_DSA(); + e5 = ENGINE_get_cipher_engine(C); + +The results would be as follows; + + assert(e1 == X); + assert(e2 == Y); + assert(e3 == X); + assert(e4 == Y); + assert(e5 == NULL); + +=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 "load"ed, 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 have control over. 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 operation, 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 initialise, +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 use with RSA 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 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 allow settings to passed +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 password-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 same 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 from a structural +reference to any ENGINE. It is first important to 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 a symbol, +ENGINE_CMD_BASE, that all control commands implemented by ENGINEs 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 by which to process these +queries. An ENGINE has 3 properties it exposes that can affect this behaviour; +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 independantly 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)>, +L<RSA_new_method(3)|RSA_new_method(3)> + +=cut diff --git a/crypto/openssl/doc/crypto/evp.pod b/crypto/openssl/doc/crypto/evp.pod index edf47db..b3ca143 100644 --- a/crypto/openssl/doc/crypto/evp.pod +++ b/crypto/openssl/doc/crypto/evp.pod @@ -24,6 +24,13 @@ functions. The B<EVP_Digest>I<...> functions provide message digests. Algorithms are loaded with OpenSSL_add_all_algorithms(3). +All the symmetric algorithms (ciphers) and digests can be replaced by ENGINE +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. + =head1 SEE ALSO L<EVP_DigestInit(3)|EVP_DigestInit(3)>, @@ -32,6 +39,7 @@ L<EVP_OpenInit(3)|EVP_OpenInit(3)>, L<EVP_SealInit(3)|EVP_SealInit(3)>, L<EVP_SignInit(3)|EVP_SignInit(3)>, L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, -L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)> +L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>, +L<engine(3)|engine(3)> =cut diff --git a/crypto/openssl/doc/crypto/hmac.pod b/crypto/openssl/doc/crypto/hmac.pod index f86e7d7..3976baf 100644 --- a/crypto/openssl/doc/crypto/hmac.pod +++ b/crypto/openssl/doc/crypto/hmac.pod @@ -13,11 +13,16 @@ authentication code int key_len, const unsigned char *d, int n, unsigned char *md, unsigned int *md_len); + void HMAC_CTX_init(HMAC_CTX *ctx); + void HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, const EVP_MD *md); + void HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md); void HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); void 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 @@ -39,13 +44,31 @@ B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. B<key> and B<evp_md> may be B<NULL> if a key and hash function have been set in a previous call to HMAC_Init() for that B<HMAC_CTX>. -HMAC_cleanup() erases the key and other data from the B<HMAC_CTX>. +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. +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 function B<evp_md> and key B<key>. Either can be NULL, in which +case the existing one will be reused. HMAC_CTX_init() must have been +called 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>. HMAC_Update() can be called repeatedly with chunks of the message to be authenticated (B<len> bytes at B<data>). @@ -57,8 +80,8 @@ must have space for the hash function output. HMAC() returns a pointer to the message authentication code. -HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() do not -return values. +HMAC_CTX_init(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and +HMAC_CTX_cleanup() do not return values. =head1 CONFORMING TO @@ -73,4 +96,7 @@ L<sha(3)|sha(3)>, L<evp(3)|evp(3)> 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. + =cut diff --git a/crypto/openssl/doc/crypto/lhash.pod b/crypto/openssl/doc/crypto/lhash.pod index 4e87aee..dcdbb43 100644 --- a/crypto/openssl/doc/crypto/lhash.pod +++ b/crypto/openssl/doc/crypto/lhash.pod @@ -2,43 +2,108 @@ =head1 NAME -lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, -lh_doall_arg, lh_error - dynamic hash table +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> - LHASH *lh_new(unsigned long (*hash)(/*void *a*/), - int (*compare)(/*void *a,void *b*/)); + LHASH *lh_new(LHASH_HASH_FN_TYPE hash, LHASH_COMP_FN_TYPE compare); void lh_free(LHASH *table); void *lh_insert(LHASH *table, void *data); void *lh_delete(LHASH *table, void *data); void *lh_retrieve(LHASH *table, void *data); - void lh_doall(LHASH *table, void (*func)(/*void *b*/)); - void lh_doall_arg(LHASH *table, void (*func)(/*void *a,void *b*/), + void lh_doall(LHASH *table, LHASH_DOALL_FN_TYPE func); + void lh_doall_arg(LHASH *table, LHASH_DOALL_ARG_FN_TYPE func, void *arg); int lh_error(LHASH *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 dynamic hash tables. The hash table entries can be arbitrary structures. Usually they consist of key and value fields. -lh_new() creates a new B<LHASH> structure. B<hash> takes a pointer to -the structure and returns an unsigned long hash value of 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. B<compare> takes two arguments, and returns 0 if their keys are -equal, non-zero otherwise. +lh_new() creates a new B<LHASH> 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_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(f_name,o_type) \ + unsigned long f_name##_LHASH_HASH(const void *); + #define IMPLEMENT_LHASH_HASH_FN(f_name,o_type) \ + unsigned long f_name##_LHASH_HASH(const void *arg) { \ + o_type a = (o_type)arg; \ + return f_name(a); } + #define LHASH_HASH_FN(f_name) f_name##_LHASH_HASH + + #define DECLARE_LHASH_COMP_FN(f_name,o_type) \ + int f_name##_LHASH_COMP(const void *, const void *); + #define IMPLEMENT_LHASH_COMP_FN(f_name,o_type) \ + int f_name##_LHASH_COMP(const void *arg1, const void *arg2) { \ + o_type a = (o_type)arg1; \ + o_type b = (o_type)arg2; \ + return f_name(a,b); } + #define LHASH_COMP_FN(f_name) f_name##_LHASH_COMP + + #define DECLARE_LHASH_DOALL_FN(f_name,o_type) \ + void f_name##_LHASH_DOALL(const void *); + #define IMPLEMENT_LHASH_DOALL_FN(f_name,o_type) \ + void f_name##_LHASH_DOALL(const void *arg) { \ + o_type a = (o_type)arg; \ + f_name(a); } + #define LHASH_DOALL_FN(f_name) f_name##_LHASH_DOALL + + #define DECLARE_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \ + void f_name##_LHASH_DOALL_ARG(const void *, const void *); + #define IMPLEMENT_LHASH_DOALL_ARG_FN(f_name,o_type,a_type) \ + void f_name##_LHASH_DOALL_ARG(const void *arg1, const void *arg2) { \ + o_type a = (o_type)arg1; \ + a_type b = (a_type)arg2; \ + f_name(a,b); } + #define LHASH_DOALL_ARG_FN(f_name) f_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_hash, const STUFF *) + static IMPLEMENT_LHASH_COMP_FN(STUFF_cmp, const STUFF *); + /* ... */ + int main(int argc, char *argv[]) { + /* Create the new hash table using the hash/compare wrappers */ + LHASH *hashtable = lh_new(LHASH_HASH_FN(STUFF_hash), + LHASH_COMP_FN(STUFF_cmp)); + /* ... */ + } lh_free() frees the B<LHASH> structure B<table>. Allocated hash table entries will not be freed; consider using lh_doall() to deallocate any -remaining entries in the hash table. +remaining entries in the hash table (see below). lh_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 @@ -52,23 +117,53 @@ a structure with the key field(s) set; the function will return a pointer to a fully populated structure. lh_doall() will, for every entry in the hash table, call B<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. When doing this, be careful if you -delete entries from the hash table in B<func>: 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 hash-E<gt>down_load=0 before you -start. This will stop the hash table ever being decreased in size. - -lh_doall_arg() is the same as lh_doall() except that B<func> will -be called with B<arg> as the second argument. - +the data item as its parameter. For lh_doall() and lh_doall_arg(), +function pointer casting should be avoided in the callbacks (see +B<NOTE>) - instead, either declare the callbacks to match the +prototype required in lh_new() or use the declare/implement macros to +create type-safe 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(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_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); + /* Then the hash table itself can be deallocated */ + lh_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_doall_arg() is the same as lh_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(const STUFF *a, BIO *output_bio); + /* Implement a prototype-compatible wrapper for "STUFF_print" */ + static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF_print, const STUFF *, BIO *) + /* ... then later in the code ... */ + /* Print out the entire hashtable to a particular BIO */ + lh_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), logging_bio); + lh_error() can be used to determine if an error occurred in the last operation. lh_error() is a macro. @@ -91,6 +186,45 @@ otherwise. lh_free(), lh_doall() and lh_doall_arg() return no values. +=head1 NOTE + +The various LHASH macros and callback types exist to make it possible +to write type-safe 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_insert() returns B<NULL> both for success and error. @@ -131,7 +265,7 @@ 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 you compare function. +will be much less expensive that 10 calls to your compare function. lh_strhash() is a demo string hashing function: @@ -152,4 +286,9 @@ 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. + =cut diff --git a/crypto/openssl/doc/crypto/pem.pod b/crypto/openssl/doc/crypto/pem.pod new file mode 100644 index 0000000..a4f8cc3 --- /dev/null +++ b/crypto/openssl/doc/crypto/pem.pod @@ -0,0 +1,476 @@ +=pod + +=head1 NAME + +PEM - 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 algoritm 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 foobar structure. + +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(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(bp, &x, 0, NULL); + +where B<x> already contains a valid certificate, may not work, whereas: + + X509_free(x); + x = PEM_read_bio(bp, NULL, 0, NULL); + +is guaranteed to work. + +=head1 RETURN CODES + +The read routines return either a pointer to the structure read or NULL +is an error occurred. + +The write routines return 1 for success or 0 for failure. diff --git a/crypto/openssl/doc/crypto/rand.pod b/crypto/openssl/doc/crypto/rand.pod index 96901f1..1c068c8 100644 --- a/crypto/openssl/doc/crypto/rand.pod +++ b/crypto/openssl/doc/crypto/rand.pod @@ -8,13 +8,14 @@ rand - pseudo-random number generator #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, int entropy); int RAND_status(void); - void RAND_screen(void); int RAND_load_file(const char *file, long max_bytes); int RAND_write_file(const char *file); @@ -22,14 +23,31 @@ rand - pseudo-random number generator int RAND_egd(const char *path); - void RAND_set_rand_method(RAND_METHOD *meth); - RAND_METHOD *RAND_get_rand_method(void); + 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 recommened +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 diff --git a/crypto/openssl/doc/crypto/rsa.pod b/crypto/openssl/doc/crypto/rsa.pod index ec7458c..45ac53f 100644 --- a/crypto/openssl/doc/crypto/rsa.pod +++ b/crypto/openssl/doc/crypto/rsa.pod @@ -7,6 +7,7 @@ rsa - RSA public key cryptosystem =head1 SYNOPSIS #include <openssl/rsa.h> + #include <openssl/engine.h> RSA * RSA_new(void); void RSA_free(RSA *rsa); @@ -15,13 +16,17 @@ rsa - RSA public key cryptosystem 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(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); @@ -31,15 +36,14 @@ rsa - RSA public key cryptosystem int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); void RSA_blinding_off(RSA *rsa); - void RSA_set_default_method(RSA_METHOD *meth); - RSA_METHOD *RSA_get_default_method(void); - RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth); - RSA_METHOD *RSA_get_method(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_PKCS1_RSAref(void); RSA_METHOD *RSA_null_method(void); - int RSA_flags(RSA *rsa); - RSA *RSA_new_method(RSA_METHOD *method); + 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); @@ -49,11 +53,6 @@ rsa - RSA public key cryptosystem int RSA_set_ex_data(RSA *r,int idx,char *arg); char *RSA_get_ex_data(RSA *r, int idx); - 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_ASN1_OCTET_STRING(int dummy, unsigned char *m, unsigned int m_len, unsigned char *sigret, unsigned int *siglen, RSA *rsa); @@ -90,6 +89,14 @@ 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 @@ -101,7 +108,7 @@ 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<RSA_new(3)|RSA_new(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)>, diff --git a/crypto/openssl/doc/crypto/threads.pod b/crypto/openssl/doc/crypto/threads.pod index 136844b..afa45cd 100644 --- a/crypto/openssl/doc/crypto/threads.pod +++ b/crypto/openssl/doc/crypto/threads.pod @@ -53,7 +53,7 @@ OpenSSL can safely be used in multi-threaded applications provided that at least two callback functions are set. locking_function(int mode, int n, const char *file, int line) is -needed to perform locking on shared data structures. +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. diff --git a/crypto/openssl/doc/crypto/ui.pod b/crypto/openssl/doc/crypto/ui.pod new file mode 100644 index 0000000..2b3535a --- /dev/null +++ b/crypto/openssl/doc/crypto/ui.pod @@ -0,0 +1,194 @@ +=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. 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 really 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/crypto/openssl/doc/crypto/ui_compat.pod b/crypto/openssl/doc/crypto/ui_compat.pod new file mode 100644 index 0000000..9ab3c69 --- /dev/null +++ b/crypto/openssl/doc/crypto/ui_compat.pod @@ -0,0 +1,55 @@ +=pod + +=head1 NAME + +des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw - +Compatibility user interface functions + +=head1 SYNOPSIS + + 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/crypto/openssl/doc/openssl.txt b/crypto/openssl/doc/openssl.txt index 5da519e..432a17b 100644 --- a/crypto/openssl/doc/openssl.txt +++ b/crypto/openssl/doc/openssl.txt @@ -344,7 +344,7 @@ the extension. Examples: -subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/ +subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ subjectAltName=email:my@other.address,RID:1.2.3.4 Issuer Alternative Name. diff --git a/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod b/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod index af326c2..82676b2 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_add_session.pod @@ -37,6 +37,14 @@ 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 surpressed 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 diff --git a/crypto/openssl/doc/ssl/SSL_CTX_ctrl.pod b/crypto/openssl/doc/ssl/SSL_CTX_ctrl.pod index 4228225..fb6adcf 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_ctrl.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_ctrl.pod @@ -8,10 +8,10 @@ SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal hand #include <openssl/ssl.h> - long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, char *parg); + 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, char *parg); + long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg); long SSL_callback_ctrl(SSL *, int cmd, void (*fp)()); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod index 723fc14..c0f4f85 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_cert_verify_callback.pod @@ -8,38 +8,36 @@ SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure #include <openssl/ssl.h> - void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(), - char *arg); - int (*callback)(); + 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 -B<ctx>. SSL objects, that are created from B<ctx> inherit the setting valid at -the time, L<SSL_new(3)|SSL_new(3)> is called. B<arg> is currently ignored. +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 B<callback> is specified via +If a verification callback I<callback> is specified via SSL_CTX_set_cert_verify_callback(), the supplied callback function is called -instead. By setting B<callback> to NULL, the default behaviour is restored. +instead. By setting I<callback> to NULL, the default behaviour is restored. -When the verification must be performed, B<callback> will be called with -the argument callback(X509_STORE_CTX *x509_store_ctx). The arguments B<arg> -that can be specified when setting B<callback> are currently ignored. +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>. -B<callback> should return 1 to indicate verification success and 0 to -indicate verification failure. If SSL_VERIFY_PEER is set and B<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 B<x509_store_ctx>, so that the calling application will be informed +member of I<x509_store_ctx> so that the calling application will be informed about the detailed result of the verification procedure! -Within B<x509_store_ctx>, B<callback> has access to the B<verify_callback> +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 @@ -56,12 +54,6 @@ the B<verify_callback> function. =head1 BUGS -It is possible to specify arguments to be passed to the verification callback. -Currently they are however not passed but ignored. - -The B<callback> function is not specified via a prototype, so that no -type checking takes place. - =head1 RETURN VALUES SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. @@ -72,4 +64,12 @@ 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/crypto/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod new file mode 100644 index 0000000..798e844 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_generate_session_id.pod @@ -0,0 +1,150 @@ +=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/crypto/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod new file mode 100644 index 0000000..da68cb9 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_max_cert_list.pod @@ -0,0 +1,77 @@ +=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/crypto/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod new file mode 100644 index 0000000..0015e6e --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_msg_callback.pod @@ -0,0 +1,99 @@ +=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_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); + void SSL_set_msg_callback_arg(SSL_CTX *ctx, void *arg); + +=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/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod index 5c07e53..f5e2ec3 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod @@ -100,18 +100,6 @@ doing a re-connect, always takes the first cipher in the cipher list. ... -=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_DONT_INSERT_EMPTY_FRAGMENTS Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol @@ -133,6 +121,18 @@ 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 @@ -142,7 +142,7 @@ 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. -SSL_OP_SINGLE_DH_USE should therefore be enabled whenever +B<SSL_OP_SINGLE_DH_USE> should therefore be enabled whenever temporary/ephemeral DH parameters are used. =item SSL_OP_EPHEMERAL_RSA @@ -157,6 +157,14 @@ SSL/TLS specifications and may lead to interoperability problems with clients and should therefore never be used. Ciphers with EDH (ephemeral Diffie-Hellman) key exchange should be used instead. +=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 his list of preferences to the client and the client chooses. + =item SSL_OP_PKCS1_CHECK_1 ... @@ -187,6 +195,12 @@ Do not use the SSLv3 protocol. Do not use the TLSv1 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. + =back =head1 RETURN VALUES @@ -205,7 +219,13 @@ L<dhparam(1)|dhparam(1)> =head1 HISTORY -SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6. +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 diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod index 9aa6c6b..c5d2f43 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -26,12 +26,14 @@ 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 decides whether it -agrees in reusing the session or starts the handshake for a new session. +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 lookup up the session in its internal session storage. If -the session is not found in internal storage or internal storage is -deactivated, the server will try the external storage if available. +A server will lookup 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 @@ -57,9 +59,10 @@ 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 session is looked up in the internal session cache. -If the session is found, the server will try to reuse the session. -This is the default. +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 @@ -77,12 +80,32 @@ explicitly by the application. =item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP -By setting this flag sessions are cached in the internal storage but -they are not looked up automatically. If an external session cache -is enabled, sessions are looked up in the external cache. As automatic -lookup only applies for SSL/TLS servers, the flag has no effect on +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. @@ -98,6 +121,7 @@ SSL_CTX_get_session_cache_mode() returns the currently set cache mode. 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)>, @@ -105,4 +129,9 @@ 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/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod index 5bb21ca..d15b2a3 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_verify.pod @@ -235,7 +235,7 @@ L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>). * 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) + 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); diff --git a/crypto/openssl/doc/ssl/SSL_alert_type_string.pod b/crypto/openssl/doc/ssl/SSL_alert_type_string.pod index 7837589..94e28cc 100644 --- a/crypto/openssl/doc/ssl/SSL_alert_type_string.pod +++ b/crypto/openssl/doc/ssl/SSL_alert_type_string.pod @@ -8,11 +8,11 @@ SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_al #include <openssl/ssl.h> - char *SSL_alert_type_string(int value); - char *SSL_alert_type_string_long(int value); + const char *SSL_alert_type_string(int value); + const char *SSL_alert_type_string_long(int value); - char *SSL_alert_desc_string(int value); - char *SSL_alert_desc_string_long(int value); + const char *SSL_alert_desc_string(int value); + const char *SSL_alert_desc_string_long(int value); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/ssl/SSL_rstate_string.pod b/crypto/openssl/doc/ssl/SSL_rstate_string.pod index 6dbbb99..bdb8a1f 100644 --- a/crypto/openssl/doc/ssl/SSL_rstate_string.pod +++ b/crypto/openssl/doc/ssl/SSL_rstate_string.pod @@ -8,8 +8,8 @@ SSL_rstate_string, SSL_rstate_string_long - get textual description of state of #include <openssl/ssl.h> - char *SSL_rstate_string(SSL *ssl); - char *SSL_rstate_string_long(SSL *ssl); + const char *SSL_rstate_string(SSL *ssl); + const char *SSL_rstate_string_long(SSL *ssl); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/ssl/SSL_state_string.pod b/crypto/openssl/doc/ssl/SSL_state_string.pod index 4404595..b4be1aa 100644 --- a/crypto/openssl/doc/ssl/SSL_state_string.pod +++ b/crypto/openssl/doc/ssl/SSL_state_string.pod @@ -8,8 +8,8 @@ SSL_state_string, SSL_state_string_long - get textual description of state of an #include <openssl/ssl.h> - char *SSL_state_string(SSL *ssl); - char *SSL_state_string_long(SSL *ssl); + const char *SSL_state_string(SSL *ssl); + const char *SSL_state_string_long(SSL *ssl); =head1 DESCRIPTION diff --git a/crypto/openssl/doc/ssl/ssl.pod b/crypto/openssl/doc/ssl/ssl.pod index 2dcee03..3dc5358 100644 --- a/crypto/openssl/doc/ssl/ssl.pod +++ b/crypto/openssl/doc/ssl/ssl.pod @@ -317,6 +317,10 @@ protocol context defined in the B<SSL_CTX> structure. =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); @@ -347,7 +351,7 @@ appropriate size (using ???) and return it. long B<SSL_set_tmp_rsa_callback>(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength)); -The same as L<"SSL_CTX_set_tmp_rsa_callback">, except it operates on an SSL +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)) @@ -576,6 +580,10 @@ connection defined in the B<SSL> structure. =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); @@ -669,8 +677,11 @@ 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_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, diff --git a/crypto/openssl/doc/standards.txt b/crypto/openssl/doc/standards.txt index 61ccc5d..44d263b 100644 --- a/crypto/openssl/doc/standards.txt +++ b/crypto/openssl/doc/standards.txt @@ -24,7 +24,8 @@ http://www.rsasecurity.com/rsalabs/pkcs/. Implemented: ------------ -These are documents that describe things that are implemented in OpenSSL. +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) @@ -41,9 +42,6 @@ These are documents that describe things that are implemented in OpenSSL. 2268 A Description of the RC2(r) Encryption Algorithm. R. Rivest. January 1998. (Format: TXT=19048 bytes) (Status: INFORMATIONAL) -2314 PKCS 10: Certification Request Syntax Version 1.5. B. Kaliski. - March 1998. (Format: TXT=15814 bytes) (Status: INFORMATIONAL) - 2315 PKCS 7: Cryptographic Message Syntax Version 1.5. B. Kaliski. March 1998. (Format: TXT=69679 bytes) (Status: INFORMATIONAL) @@ -51,14 +49,44 @@ These are documents that describe things that are implemented in OpenSSL. J. Staddon. October 1998. (Format: TXT=73529 bytes) (Obsoletes RFC2313) (Status: INFORMATIONAL) -2459 Internet X.509 Public Key Infrastructure Certificate and CRL - Profile. R. Housley, W. Ford, W. Polk, D. Solo. January 1999. - (Format: TXT=278438 bytes) (Status: PROPOSED STANDARD) - 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) + +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) + Related: -------- @@ -84,19 +112,60 @@ STARTTLS documents. Certification and Related Services. B. Kaliski. February 1993. (Format: TXT=17537 bytes) (Status: PROPOSED STANDARD) -2487 SMTP Service Extension for Secure SMTP over TLS. P. Hoffman. - January 1999. (Format: TXT=15120 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) -2712 Addition of Kerberos Cipher Suites to Transport Layer Security - (TLS). A. Medvinsky, M. Hur. October 1999. (Format: TXT=13763 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 @@ -105,6 +174,77 @@ STARTTLS documents. 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) + "Securing FTP with TLS", 01/27/2000, <draft-murray-auth-ftp-ssl-05.txt> @@ -114,8 +254,3 @@ To be implemented: These are documents that describe things that are planed to be implemented in the hopefully short future. -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) - |
